m64_0f5b8210b0a4 / AGENT.md
pi coding agent (Qwen3.8-Flash-Next IQ3_S on Strata, local)
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 pi 0.73.1 (badlogic/pi-mono), run in its one-shot JSON mode, once per message. The model is Qwen3.8-Flash-Next (Qwen's 125B-A6B mixture-of-experts model; ISTA-DASLab's GSQ-RCO IQ3_S GGUF), served by Strata 0.2.13's DGX Spark engine in the same container with its full 262144-token window, MTP drafting and pictures on: prompts and code stay on this machine.
Each session works in its own empty directory, and you can list, download and upload its
files. The agent runs in a sandbox, as a non-root user. It has no network unless the person
who served it granted some (then every connection is logged: network in GET /status), so
give it work that needs no downloads. Python 3, 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
- 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}}
Quick start
SID=$(curl -s -X POST {{BASE_URL}}/v1/sessions {{AUTH}} \
-H "Content-Type: application/json" -d '{}' | 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, 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 (pi's --continue).
text(string, required): what to do.wait(bool, defaulttrue): withtrue, 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. Withfalse, it returns202at once; follow the turn on the events stream, whoseturn.endevent carries the same fields as the reply below.
Reply (with wait: true):
{"role": "assistant", "text": "Created hello.py ... it prints: hi",
"tools": [{"tool": "write", "status": "completed", "input": {...}, "output": "..."},
{"tool": "bash", "status": "completed", "input": {"command": "python3 hello.py"}, "output": "hi\n"}],
"exit_code": 0, "elapsed_s": 6.2}
tools lists every tool call in the turn, and each output is cut to 4000 characters.
A non-zero exit_code means pi itself failed (for example, the model ran out of context);
the reply then carries an error string with the end of pi's error output.
A second message to a session whose turn is still running returns 409.
GET /v1/sessions/{id}/events
Server-sent events for this session, one data: JSON line each:
{"type": "turn.start", "text": ...}, then one {"type": "output", "line": ...} per line pi
prints (each line is one of pi's own JSON events: messages, tool_execution_start,
tool_execution_end, ...), then {"type": "turn.end", ...} with the same fields as the
wait: true reply. The stream stays open; close it when you are done.
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}.
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 (pi's process is killed). A messages request waiting on
that turn then returns with a non-zero exit_code.
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 (it fetches Strata's draft layer, ~5 GB of range requests) and downloads about 85 GB of weights; after that the engine is ready in a few minutes (budgeted at 900 s).
- Strata serves one request at a time; sessions can run in parallel, but their model calls queue.
- 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. SendAuthorization: Bearer <token>.503withRetry-Afterwhile the service is still starting: wait and retry.404: unknown session id, file not found, or a route this service does not offer.409: the session is still busy with a turn.400: the body is not a JSON object,textis missing, or a path escapes the session.5xxotherwise: retry once, then checkGET /status.