bonsai serve exposes one canonical workspace over HTTP + SSE. The API is
unstable, version experimental-v0, rooted at /api/experimental/v0.
This is a single-operator preview, not a multi-user service. See
server-changelog.md for contract changes.
Build with the stable Rust toolchain:
cargo build --release --locked
# Run in the workspace, not the source checkout unless that is your workspace.
/path/to/bonsai serve
The default listener is 127.0.0.1:0. Startup reports the actual URL and a
token file path and ID, never the secret. $BONSAI_HOME (default
~/.bonsai) must be outside the workspace. Do not publish the token file or
put it in source control. Its mode is 0600; SQLite stores only its hash.
Choose/authorize a provider locally first using the normal TUI. BONSAI_PROVIDER
can select an authorized provider at startup; normal provider environment
variables apply. Credentials cannot be supplied or edited through HTTP.
Project-owned hooks/MCP/config run only when the workspace was trusted locally
in the TUI. An untrusted workspace remains restricted: API authentication does
not grant repository trust. Server autonomy starts at Ask; HTTP cannot change it.
Create and resume never start a model or restore a goal into execution.
A second server for the same canonical workspace fails fast. The OS owner lock is separate from persisted session claims and is retained through runtime drain. Stop with Ctrl-C / SIGINT and wait for successful exit. A failed or timed-out drain is an error, not a successful shutdown. SIGKILL is crash recovery, not clean shutdown; after restart explicitly resume and submit a new command.
Options:
| Option | Meaning |
|---|---|
--bind IP:PORT |
Literal IP only; defaults to 127.0.0.1:0 |
--allow-remote |
Explicit opt-in for a non-loopback bind |
--tls-cert PATH --tls-key PATH |
PEM certificate/key; both required together |
--allow-origin https://client.example |
Repeatable, exact origin, no trailing slash |
--allow-host api.example:443 |
Repeatable exact Host authority |
Non-loopback requires both remote opt-in and TLS. Prefer loopback behind a trusted tunnel or TLS reverse proxy. Forwarded headers are not identity; configure the exact Host the proxy sends. No wildcard CORS, cookies, query credentials or no-auth mode. Browser preflight is public only after Host/Origin validation; the actual resource request always requires Bearer. Browser clients need fetch streaming with Authorization, not credential-less EventSource.
Run token commands from the same workspace and with the same BONSAI_HOME:
bonsai serve token mint --output /private/operator/read-token --ttl 3600 --scope read --session 12
bonsai serve token revoke TOKEN_ID
The output must be a new file outside the workspace in an existing directory.
TTL is 1–86400 seconds (default 3600). Repeat --scope and --session to narrow
access; omitting scopes grants all four; omitting sessions makes it workspace-wide.
There is no HTTP mint endpoint. Revocation/expiry stops new commands and streams,
not already accepted execution or its children. Use a different valid control
token to interrupt. Tokens do not roll back completed effects.
| Scope | Operations |
|---|---|
read |
list/get/events, including sensitive prompts and tool/file content |
control |
create/resume/messages/interrupt; create requires workspace-wide scope |
respond |
respond to a particular currently pending interaction |
artifacts |
list/download registered artifacts |
Read is not public status access. Artifact isolation does not hide information already present in transcripts. Redaction is best-effort, not a guarantee of finding secrets in arbitrary user/tool content.
Every response, including errors/downloads, carries
Bonsai-API-Version: experimental-v0. Errors have
{"error":{"code":"scope_denied","message":"scope_denied","request_id":"..."}}.
Use code/status, not local diagnostic text. Unknown fields in command bodies
are rejected. Message input is user text only, never system prompts or raw tool
results, arbitrary paths, safety settings or provider credentials.
All mutation bodies contain a caller-chosen request_id (1–128 ASCII letters,
digits, -_.:). Persist it before sending and reuse only for identical retries.
A duplicate returns the recorded result; different content under that ID conflicts.
An admitted request interrupted by crash is not replayed. An unfinished mutation
may require operator recovery/new ID; never blindly reissue effects with new IDs.
Dedupe is reauthorized, not a public result cache. Interaction responses are also
correlated to session/run/prompt and consumed once by the engine.
| Method | Relative path | Body / behavior |
|---|---|---|
| POST | /sessions |
{request_id} → 201 + session_id |
| GET | /sessions?after=0&limit=50 |
workspace/scope-filtered list; limit 1–100 |
| GET | /sessions/{id}?offset=0&limit=100 |
paginated transcript, state, goal, pending, usage; loaded sessions also plan/todo/budget |
| GET | /sessions/{id}/goal |
current goal and elapsed milliseconds, or null when none exists |
| POST | /sessions/{id}/goal |
{request_id,action,objective?}; set, pause, resume, or clear the goal |
| POST | /sessions/{id}/resume |
{request_id}; claims/loads only |
| POST | /sessions/{id}/messages |
{request_id,text} → 202 + run_id, acceptance not completion |
| POST | /sessions/{id}/interrupt |
{request_id}; cancellation requested, not yet stopped |
| GET | /sessions/{id}/events |
SSE; requires loaded session |
| POST | /sessions/{id}/interactions/{prompt_id}/responses |
{request_id,run_id,answer} |
| GET | /sessions/{id}/artifacts |
explicitly registered artifacts |
| GET | /sessions/{id}/artifacts/{artifact_id} |
attachment, octet-stream, nosniff |
Only one session may execute, including children/background tasks/terminals.
During an active goal run, messages can be queued as follow-ups to that same
run, with a limit of 64 per run. Other busy chat requests conflict. A queued
message is accepted before it is delivered: the message_delivery event
reports delivered when the agent receives it or interrupted if the run
ends first. Retrying the same request ID returns its recorded state; after a
crash, unresolved accepted requests are marked interrupted on resume. Switching
sessions may release an idle runtime, never silently cancel an active runtime.
Status, interrupt and interaction responses remain responsive during execution.
The goal endpoint is a point-in-time read of the persisted record and requires
the session’s read scope. It works for unloaded sessions. Loaded-session
snapshots include the goal, and the event stream publishes ordered goal
events containing the current record or null after removal. elapsed_ms (and
goal_elapsed_ms in session snapshots) combines recorded run time with the
verified live run, excluding paused and unobserved crash gaps. Poll the endpoint
for timer updates; goal events are emitted on state changes, not on each tick.
Goal controls require control scope
and a loaded session. set requires an objective; pause, resume, and
clear do not accept one. Setting or replacing an objective never starts a
model run. Replacing a goal or pausing an active goal requests cancellation
of the current run; resume is available after that run settles. Clients must
submit a separate message to start work and cannot set completion or usage.
A pending prompt exposes its kind and allowed decisions. Permission/web/extension/
hook prompts use {"kind":"permission","decision":"allow_once"} or deny;
other permission decisions are allowed only as advertised. Sandbox prompts use
{"kind":"sandbox","decision":"allow_once"} (or allow_for_session/deny).
Questions use {"kind":"question","choices":[0]}; null cancels. There is no
HTTP approve-all. Unknown/stale/wrong-run/wrong-type answers cannot grant authority.
Use a private header file, not the secret in process arguments:
BASE=http://127.0.0.1:PORT/api/experimental/v0
TOKEN_FILE=/private/path/reported-at-startup
umask 077
AUTH=$(mktemp)
printf 'Authorization: Bearer %s\n' "$(cat "$TOKEN_FILE")" > "$AUTH"
curl -H @"$AUTH" -H 'Content-Type: application/json' -d '{"request_id":"create-1"}' "$BASE/sessions"
curl -H @"$AUTH" -H 'Content-Type: application/json' -d '{"request_id":"resume-1"}' "$BASE/sessions/12/resume"
curl -N -H @"$AUTH" "$BASE/sessions/12/events"
# In another terminal, using the same private header file:
curl -H @"$AUTH" -H 'Content-Type: application/json' -d '{"request_id":"chat-1","text":"Inspect README.md"}' "$BASE/sessions/12/messages"
curl -H @"$AUTH" -H 'Content-Type: application/json' -d '{"request_id":"answer-1","run_id":"RUN","answer":{"kind":"permission","decision":"deny"}}' "$BASE/sessions/12/interactions/1/responses"
rm "$AUTH"
examples/server_client.py requires Python 3.10+ and only the standard library. It refuses redirects and ambient proxies, never auto-approves prompts and verifies the API version:
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" list
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" --request-id create-2 create
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" goal 12 set "Inspect README.md"
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" goal 12 get
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" message 12 "Inspect README.md"
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" events 12
python3 examples/server_client.py --url "$BASE" --token-file "$TOKEN_FILE" answer 12 RUN 1 '{"kind":"permission","decision":"deny"}'
Use goal 12 pause, goal 12 resume, or goal 12 clear for the other
controls. Mutations return an acknowledgement; use goal 12 get for the
current record. Setting or resuming a goal does not start a run: send a
message separately.
GET /sessions/{id}/events streams Server-Sent Events; each data frame is one
JSON object whose kind selects the payload. The published set is fixed in
server-contract.json under event_kinds, and a normal
cargo test run fails when the server projects a kind that is not published or
when this table lists one it no longer emits, so code, fixtures and this table
cannot drift apart.
kind |
payload | behavior |
|---|---|---|
reset |
{resync_required: true} |
The cursor cannot continue the stream: reconnect without one and replace local state from the fresh snapshot. |
user_message |
{text} |
User text accepted for a run. |
message_delivery |
{run_id, request_id, state} |
A queued follow-up was delivered, or interrupted because its run ended first. |
assistant_delta |
{text} |
Incremental assistant text. |
assistant_done |
{} |
The current assistant message ended. |
reasoning_delta |
{text} |
Incremental reasoning text, when the provider streams it. |
attempt_started |
{} |
A provider attempt began; a retry starts another one. |
attempt_discarded |
{} |
Output from the current attempt was discarded and must be dropped. |
tool_started |
{id, name, arguments} |
A tool call began; arguments stays a raw JSON string. |
tool_output |
{id, text} |
Incremental output from a running call. |
tool_result |
{id, result} |
Terminal result carrying the typed envelope, including file diffs. |
usage |
{prompt_tokens, completion_tokens, cost_micros} |
Cumulative session usage; cost_micros is null when pricing is unknown. |
plan |
{plan} |
Plan-canvas document replacement. |
todos |
{todos} |
Todo list replacement. |
goal |
{goal} |
Current goal record, or null after removal. |
completion |
{report} |
Terminal completion report, published only after its writes land. |
status |
{text} |
Progress line for humans; never authoritative state. |
error |
{code, message} |
Fixed, sanitized class of execution failure. |
interaction |
{request} |
A prompt awaiting an answer; the shapes are above. |
interaction_resolved |
{request_id} |
That prompt was answered, cancelled, or invalidated. |
lifecycle |
{run_id, state} |
Run lifecycle transition; run_id is null when no run owns it. |
tool_result.result is the surface-neutral envelope: status (succeeded,
failed, started, skipped, interrupted), preview (the short display
string), and content, a tagged object whose type picks the shape: content
(parts), command (rendered command, stdout, stderr, exit code, timeout,
truncation), edit (summary plus diff), context (provenance plus content),
background_task, subagent, wait. background_task_id and subagent_id
appear only when set.
A file mutation arrives as content.type == "edit" with a diff of {path,
status, hunks, truncated, old_size, new_size, added_lines, removed_lines,
additional_files}. status is created, modified or deleted; a hunk is
{old_start, new_start, lines} and a line is {kind, content, old_line,
new_line} with kind one of context, added, removed. additional_files
carries further files written by the same atomic call, so a multi-file edit
stays structured — render those too instead of showing only path. The pinned
example is the tool_result entry in
server-contract.json.
First connection sends a consistent snapshot with watermark, then ordered newer events. Keep Last-Event-ID opaque: it includes process epoch, sink/load generation and sequence. Reconnect with that header. Valid cursors replay within a bounded in-memory window; gaps, replacement sink or restart cause explicit reset + snapshot. Heartbeat/reset do not advance the event cursor. A resync-required reset ends a lagging stream: reconnect without a cursor to obtain current state. A disconnected client never cancels work or approves pending prompts. Deltas are not a durable log. Persisted snapshots/reports are authoritative; completion is published after writes.
Body 1 MiB; pages ≤100; SSE clients 8; replay ≤1000 events/8 MiB; download ≤64 MiB; requests 30 s; shutdown 30 s; concurrent requests 32; request rate 120/s (process-wide fixed window); blocked SSE handoff 5 s. Oversize/overload yields 413/429 or explicit resync, not an unbounded queue. Existing cumulative session/child budgets still apply. Large snapshots exceeding the SSE payload bound require paginated GET; never treat reset as complete history.
Artifacts are immutable private copies with opaque ID, hash and size. Only trusted
backend qualification can publish; no filesystem browsing or model/HTTP arbitrary
path registration. Workspace tool outputs are not automatically downloadable.
The server publishes an allowlisted completion summary as a JSON attachment:
status, aggregate authorization/usage, verification status and review status only.
It excludes commands, reviewer text, paths and arbitrary diagnostics; artifacts
does not grant read. Arbitrary generated deliverables require an explicit trusted adapter. Symlink, hardlink,
replacement, size and in-copy metadata changes are rejected; download rechecks hash.
cargo test --locked --test server_preview launches a real binary with isolated
HOME/DB/workspace and mock provider, runs permissions/tools/diff, a Python request,
interrupt and restart/reconnect. Inline server tests cover token matrix, every prompt
type, artifact attacks, replay gaps, slow consumers and persistence failures.
cargo test --locked --test surface_smoke retains headless/TUI safety regressions.
server-contract.json fixtures are checked against actual Rust
request DTOs, decision decoding and event projections by normal cargo test, and
the event-kind table above is checked against the enum both ways; CI therefore
rejects fixture and documentation drift. Breaking preview changes must be
recorded in server-changelog.md with client migration
guidance.
No uploads, general-purpose steering outside active goal runs, provider/credential management, ACP, web UI, parallel workspaces/scheduler or stable v1 compatibility. Pending prompts and work are never automatically replayed on restart. After a hard crash, resume can return 409 until the conservative 15-second heartbeat fence expires; retry explicitly with a new request ID after a rejected/incomplete admission (an identical ID retrieves historical acceptance, not a new attempt). A live OS owner is never displaced, regardless of heartbeat age. #46 is not a claim of production multi-tenant security; ACP (#78) and the open-source web-client evaluation (#79) remain separate work.