# opencode coding agent (Qwen3.8-Flash-Next on Basalt, RTX 5090)

This service is a coding agent you drive over HTTP. You open a session, send it a task in
plain English, and it does the work: it writes files, runs shell commands and reads the
results until it is done. Then it replies. The harness is opencode 1.18.23. The model is
Qwen3.8-Flash-Next (IQ3_S pack, 384k context) on the Basalt engine, running on the RTX 5090
in this same container.

Each session works in its own empty directory, and you can list, download and upload its
files. The agent runs in a sandbox. It is not root, and it has no network access unless
the user served it with `--allow-external-network` (the public internet) or
`--allow-internal-network` (the LAN and tailnet); `network_access` in `GET /status` and
`sandbox.network` in `GET /agent?format=json` say what this run has. Without a grant,
`pip install`, `curl https://example.com` or `git clone` are blocked and logged, so give it
work that needs no downloads: Python 3.12's standard library, node 22, git, ripgrep, jq and
a C toolchain are installed.

You cannot choose the model, tools or system prompt. You send only message text and files.

## Security note
- **Anyone who can reach this service can run code in it** (inside the sandbox, on the GPU
  machine). Keep its token private.
- **Sessions are not isolated from each other.** Every session runs as the same user, in
  the same container, so an agent in one session can read and change other sessions'
  files. Use one running service per person or project, not per session.

Base URL: `{{BASE_URL}}`

## opencode in the browser
This service also exposes opencode itself on a second port, the **app port**: its terminal
interface in a browser tab (ttyd), opened on the folder `home`, one TUI per tab. Its URL is
`app_url` in `GET /status` and `GET /agent?format=json`; it is usually this service's port
+ 1. `/human/` links to it.

Files, shell commands and model calls all run in this service's container: nothing
leaves the GPU machine.
- The app port has **no per-session isolation**: it sees every session and file, and its
  project is the folder `home` (`/scratch/home`).
- It has **no params filtering**: the TUI runs the agent's tools, shell included, which is
  what the agent can already do inside its container.

## Quick start

```bash
SID=$(curl -s -X POST {{BASE_URL}}/v1/sessions {{AUTH}} \
  -H "Content-Type: application/json" -d '{"title": "demo"}' | jq -r .id)

curl -s -X POST {{BASE_URL}}/v1/sessions/$SID/messages {{AUTH}} \
  -H "Content-Type: application/json" \
  -d '{"text": "write hello.py that prints hi and run it"}' | jq '{text, steps, elapsed_s, tools: [.tools[] | {tool, status}]}'

curl -s {{BASE_URL}}/v1/sessions/$SID/files {{AUTH}}
curl -s "{{BASE_URL}}/v1/sessions/$SID/files?path=hello.py" {{AUTH}}
```

## Routes

### `POST /v1/sessions`
Creates a session with a fresh empty directory. The body is optional: `{"title": "..."}`.
Returns `201` with `{"id": "ses_...", "title": ..., "created": <unix time>}`.

### `POST /v1/sessions/{id}/messages`
Sends one task or follow-up to the session. The agent remembers earlier messages in the
same session.
- `text` (string, required): what to do.
- `wait` (bool, default `true`): with `true`, the request blocks until the agent's turn is
  over. That can take a few seconds or several minutes, so set your client timeout to at
  least 10 minutes. With `false`, it returns `202` at once; follow the turn on the events
  stream.

Reply (with `wait: true`):
```json
{"id": "msg_...", "role": "assistant", "text": "Created hello.py ... prints: hi",
 "tools": [{"tool": "write", "status": "completed", "input": {...}, "output": "..."},
           {"tool": "bash", "status": "completed", "input": {"command": "python3 hello.py"}, "output": "hi\n"}],
 "steps": 3, "tokens": {...}, "finish": "stop", "elapsed_s": 6.2}
```
`tools` lists every tool call in the turn, and each `output` is cut to 4000 characters.
When the model call itself fails (for example, the prompt is longer than the context), the reply
carries an `error` object.

### `GET /v1/sessions/{id}/events`
Server-sent events for this session: opencode's own event objects (message parts as they
stream, tool calls, `session.idle` when a turn ends), one `data:` line each. The stream
stays open; close it when you are done.

```bash
curl -sN {{BASE_URL}}/v1/sessions/$SID/events {{AUTH}}
```

### `GET /v1/sessions/{id}/files[?path=...]`
With no `path`, or a directory path, it lists entries:
`{"path": ".", "entries": [{"name": "hello.py", "type": "file", "size": 12}]}`.
`type` is `file`, `dir` or `other` (a FIFO, socket or device).

A file path returns the file's bytes as a download (`Content-Disposition: attachment`).
The agent wrote these bytes, so they are never served as a web page: the type is
`text/plain`, `image/png`, `image/jpeg`, `image/gif` or `image/webp` when the extension
says so, and `application/octet-stream` for everything else (`.py`, `.html`, `.svg`...).
A path that leaves the session directory, contains a NUL byte, or names something other
than a regular file or directory returns `400`. A missing path returns `404`.

### `PUT /v1/sessions/{id}/files?path=...`
Uploads the raw request body to `path` in the session directory, creating parent
directories as needed. `400` if `path` exists and is not a regular file. Returns `201` with `{"written": "data/input.csv", "bytes": 1234}`.

```bash
curl -s -X PUT "{{BASE_URL}}/v1/sessions/$SID/files?path=data/input.csv" {{AUTH}} \
  --data-binary @input.csv
```

### `POST /v1/sessions/{id}/abort`
Stops the session's running turn. A `messages` request waiting on that turn then
returns early.

### `GET /v1/agent`
What this agent is: harness, model and sandbox policy.

### `GET /status`
Start-up progress: `phase` is `building`, `starting`, `loading`, `ready` or `error`.
`network` summarises the sandbox's outbound connections, and lists blocked attempts.

## Timings and concurrency
- First start builds the container image, which takes a few minutes. After that, the
  service is ready once Basalt has loaded the 87 GB pack: about a minute when it is
  in the page cache, a few minutes cold (budgeted at 300 s).
- A small task such as the quick start takes about 3–10 s, and bigger tasks take
  minutes. Generation runs at about 300 tok/s; time depends on how many steps the agent takes.
- Sessions are independent, but the model answers one request at a time: parallel
  sessions take turns. Send one message at a time per
  session, and wait for the turn to end before you send the next.
- Sessions and their files live only as long as this run of the service. Download what
  you want to keep.

## Errors
- `401`: missing or wrong token. Send `Authorization: Bearer <token>`.
- `503` with `Retry-After` while the service is still starting: wait and retry.
- `404`: unknown session id, file not found, or a route this service does not offer.
- `400`: the body is not a JSON object, `text` is missing, or a path escapes the session.
- `5xx` otherwise: retry once, then check `GET /status`.