# Agent Workspace

Base URL: https://a.renzenbrink.org

Choose either HTTP Basic authentication with username agent and the owner-provided workspace password, or send your assigned API key in the Authorization header using the Bearer scheme. Both authorize the same command and file operations. No login request is needed first. Use HTTPS. Never put credentials in URLs, shared files, logs, or command output. This is a normal HTTPS API; no MCP software is needed. Your agent must be able to make authenticated HTTP requests with JSON bodies. A browser-only search tool is insufficient.

## Run a command

Send POST /v1/exec with command. That starts Bash and returns combined stdout/stderr in output, state, and exit_code. There is no separate setup or session-creation call. For an ordinary completed command, read the output and exit code and continue your task.

Each call starts a fresh shell. Pass cwd to choose its directory (default /workspace) and env to add or override environment variables. Files and installed software persist between calls; shell variables and directory changes do not. Commands run in a shared Linux container with root access and installed utilities, Python, Node, and build tools. The host, API credentials, Tailscale, and backup administration are outside it.

Optional wait controls how long this HTTP call waits for completion (default 10 seconds, range 0–10). It does not stop the command. Optional timeout limits execution (default 3600 seconds; null disables the limit). A timeout is reported with timed_out=true.

## Continue only when needed

If state is running, the command continues in the background. Its id is the handle for reading more output, sending input, or cancelling. The continuation routes call this handle a session; you do not create or manage a separate workspace session.

Read more with GET /v1/sessions/{id}, passing the previous next_offset as offset. Optional wait holds the request for new output or completion, up to 20 seconds. If state is exited, exit_code is the process result. If state is lost, inspect error; completion could not be confirmed.

Every response contains at most 256 KiB of output. Continue reading whenever next_offset is less than available_offset, even after exit. Finish when the command has ended and next_offset equals available_offset. Offsets count bytes. Use output_base64 for exact bytes because output may replace partial UTF-8 sequences. Only the last 4 MiB are retained; truncated=true means earlier bytes were discarded. Redirect large results to files.

DELETE /v1/sessions/{id} requests cancellation; poll to confirm the final result. To send standard input, use POST /v1/sessions/{id}/input with text or data_base64. Add eof to close pipe input after the supplied bytes. The same route accepts signal (INT, TERM, KILL, HUP).

For a program that needs a terminal, set tty=true on the original exec call. Only if you need a shell that retains variables and its current directory, set interactive=true instead of supplying command. Send subsequent commands as text with newlines through the input route. Interactive shells always use a terminal; INT interrupts the foreground program. Optional cols and rows resize the terminal.

## Retries and lifetime

For executions you may need to retry, send a unique Idempotency-Key header (up to 128 characters) from the first POST /v1/exec request. Retry with the same key, API credential, and identical body to retrieve that command instead of starting it again. A changed body returns 409. Retry responses start at output offset zero, so use your saved next_offset when continuing. Input requests are not deduplicated; repeating them can send input twice.

Deduplication and command handles last only while their records remain in memory. At most 16 commands run concurrently; up to 64 records are retained, with completed records evicted as new commands arrive. API restarts lose these records and terminate attached commands. After a restart or eviction, retrying an execution may run it again: check the task's effects first. These handles do not provide durable jobs. Ordinary child processes are cleaned up when their command ends; deliberately detached processes are not durable managed jobs.

Use the same credential identity to continue a command: its original API key, or the shared password. Password users share one identity. The underlying files and processes are shared among agents.

## Files

PUT /files/{relative-path} streams the raw file body to /workspace. Parent directories are created. A successful upload replaces the destination atomically; avoid replacing a file another editor is actively changing. GET or HEAD /files/{relative-path} downloads it. Byte ranges support resuming downloads. GET /{relative-path} is also available, except reserved API routes. Paths are case-sensitive and URL-encoded. File routes intentionally reject symbolic links and traversal outside the workspace. Use Bash inside the container for operations on symbolic links or container-only files.

For a browser download without a share link, use username agent and the workspace password, or any username with your API key as the password. Do not send this credential to others. Downloads are attachments rather than executable HTML pages.

POST /v1/links accepts path and expires_in (60–604800 seconds, default 3600), returning a download URL. Anyone holding that URL can download that one path until expiry. Links refer to the current file at that path, so use a dedicated immutable copy when sharing a fixed version. DELETE /v1/links/{id} revokes it early. Revoking the issuing API key also invalidates its links. Password-created links are invalidated when the owner rotates the password and its auth_version. A link grants download only; it cannot list folders, upload, or execute commands.

## Operational limits

All agents share a container capped at 2.5 GiB RAM, 1.75 CPUs and 512 processes. They share the server disk and network. Keys grant full read/write and command access to the shared workspace, not per-folder isolation. Keep secrets out of /workspace. Mac synchronization propagates deletions; it is not an independent backup. Shared files can be concurrently edited: coordinate changes to avoid conflicts. iPhone access needs Tailscale but API calls and share links do not.

Files in /workspace are shared with Mac sync and iPhone Files. Container software and /root persist between commands, but replacing the container requires preserving those changes separately.

OpenAPI: /openapi.json. Interactive reference: /docs. Availability: /health.

## Personal file browser

The website at the base URL provides password sign-in, folder browsing, uploads, and downloads. Its session cookie permits file operations only and cannot execute commands. The same password can separately authorize commands through HTTP Basic authentication. Agents should use the command and file API described above.

Password verification is rate-limited. A 429 response includes Retry-After; respect it. Password rotation must update auth_version as well as the password hash, invalidating old browser sessions, command ownership, and password-created share links. It does not undo effects or stop already running commands. Passwords are stored as salted scrypt hashes, not plaintext, on the server. API keys remain independently revocable.