Manual contents

The Sprites transport reference

This page documents the Sprites adapter's transport contract. It covers each endpoint that Managoat.Sandbox.Sprites calls, the semantics it depends on, and the operational assumptions it makes.

The sandbox contract is the provider-neutral contract that each backend must meet. That is the Managoat.Sandbox behaviour and its conformance suite, Managoat.Sandbox.ConformanceCase, which the E2B adapter also satisfies. To evaluate a new backend, start there. This page is the reference for what the first backend provides.

The Sprites integration guide holds the setup and the cost model.

Here is the transport in one line. It is REST over HTTPS with Authorization: Bearer <token>, and one WebSocket transport for command execution.


The surface it consumes

Operation Endpoint What depends on it
Create a sprite POST /v1/sprites, JSON {"name": …}, allowed 120s. Each conversation start.
Get a sprite GET /v1/sprites/{name}, where 404 means not found. A wake, a reattach and a park.
Destroy a sprite DELETE /v1/sprites/{name}, where 404 counts as success. Terminate, a configured max-lifetime ceiling, the reaper, and account deletion. An idle suspend deliberately calls nothing, because the sprite scales to zero on its own.
List sprites GET /v1/sprites, paginated, as below. The reaper's hourly reconciliation.
Write a file PUT /v1/sprites/{name}/fs/write?path=…&workingDir=…&mode=…&mkdirParents=…, with a raw body. The env file, inline skills, and the runtime config files.
Execute, and block A WebSocket at /v1/sprites/{name}/exec. Run to exit. Managoat reads the output as it arrives, and writes package and setup output to the log while the command runs. Package installs, git clones, setup scripts, and the runtime preparation.
Execute, and stream The same WebSocket, with detachable=true. The agent turn itself.
List sessions GET /v1/sprites/{name}/exec → {"sessions": […]} A reattach after a deploy or a crash.
Attach a session A WebSocket at /v1/sprites/{name}/exec/{session_id}. A resume of a turn that runs.
Set a network policy POST /v1/sprites/{name}/policy/network, where success is exactly 204. An environment with networking_type: limited.

Pagination on GET /v1/sprites works like this. The server pages, at 50, which is its choice, and the client sends no page-size parameter. The response carries sprites, has_more and next_continuation_token. The client passes continuation_token back until has_more is false.

Managoat refuses to act on a partial list. A reconciler that saw half the account would draw exactly the wrong conclusions.


The exec transport

Command execution is a WebSocket upgrade of /v1/sprites/{name}/exec. The client sends the bearer token again on the upgrade, and has ten seconds to complete it.

The command travels in the query string. That is path, one repeated cmd for each argv entry, repeated env=KEY=VALUE pairs, and stdin=true|false. It also takes an optional dir, an optional tty with rows and cols, and an optional detachable=true.

Frames are binary, with a one-byte stream id in front.

First byte Meaning
0 stdin, client to server.
1 stdout.
2 stderr.
3 exit, and then a one-byte exit code.
4 stdin EOF, client to server.

In TTY mode the prefix disappears. A binary frame is then raw terminal bytes, and a JSON text frame carries a control message, which is exit, resize or port.

Managoat depends on three subtleties.

  • The exit code is one byte. This page said four bytes until August 2026, and our Elixir client read four. No real frame 3 ever matched, so the client discarded every one of them. Read #880 before you change this row.
  • A close with no exit frame counts as exit 0. A replacement that drops a connection and sends no frame 3 makes a failed command look successful. This rule is what turned the wrong width into silence. The client dropped the frame, the socket closed, and the command reported success.
  • The client enforces the timeout for each command. The turn itself runs unbounded, and the sandbox lifecycle ends it. The transport does not.

Sessions

detachable=true on the spawn is the contract that lets a deploy happen safely. The process on the sprite side continues when the WebSocket drops. It appears in GET /v1/sprites/{name}/exec, with id, command, created, last_activity, is_active and tty. You can re-join it at /v1/sprites/{name}/exec/{session_id}.

  • A detached session reports is_active: false while nobody holds a connection to it. Managoat deliberately does not filter on that field.
  • An attach replays the session's buffered output from the start, then tails. There is no offset parameter. Managoat removes the duplicates. It counts the bytes it already persisted for each stream, then drops that many from the head of the replay. A replacement must replay from the start, or that arithmetic breaks.

Network policy

The body is {"rules": [{"domain": …, "action": "allow"|"deny", "include": …}]}.

One semantic matters most. An empty rules list means no enforcement, which is allow-all, and not deny-all.

For a limited environment with an empty allowlist, Managoat sends an explicit {"domain": "*", "action": "deny"}. It deliberately omits include: "defaults", which would add the platform's own allowances back.

A replacement that treats rules: [] as deny-all is safer than Sprites here. One that ignores a deny rule fails the whole limited feature open.


Operational assumptions

  • Timeouts. SPRITES_TIMEOUT_MS bounds each REST call, and it is 30s by default. Create alone gets 120s. An exec command carries its own bound: 5s for a chmod, 30 to 120s for a runtime probe and the setup script, 300s for a package install, 600s for a clone, and unbounded for the turn.
  • Retries. Managoat tries a transient failure up to three times, so the first call and two retries, with exponential backoff and jitter. It does that on the provision path alone. Transient means a 5xx, a 429, a timeout or a transport error. Another 4xx fails fast, because a 401 or a 403 is a token problem, and not weather.
  • Idempotency is Managoat's job, and not the API's. A sprite name is unique for each token, as fountain-<tenant-prefix>-<8 hex>. A 409 on create means the sprite already exists. Managoat then adopts it, and raises no error. That is safe because the organization belongs to one instance (Sprites): Managoat checks no ownership before it adopts. Destroy tolerates a 404. The hourly reaper converges whatever the successful path leaked. A replacement needs stable name-keyed create and destroy semantics, and no more.
  • Errors. Any non-2xx surfaces as a status plus the decoded body. A rate-limit response carries a structured body, with sprite_creation_rate_limited, concurrent_sprite_limit_exceeded and retry_after_seconds. Managoat handles those generically today, as 429s.
  • The bill. One platform token pays for each sandbox (ADR 0005). That is why the fleet ceiling counts a sandbox from the moment a provision starts, and why the reaper exists at all.

The failure model

When Sprites is… What happens
Down at provision time. Managoat retries within bounds, then marks the conversation failed. The stage events name the step.
Down at wake time. Managoat marks the sandbox failed. The conversation stays resumable, and re-provisions on the next prompt.
Dropped mid-turn. The detachable session continues on the sprite side. A reattach picks it up, and replay-from-start plus the byte skip restores the stream.
Slow. SPRITES_TIMEOUT_MS bounds each call, and Managoat retries a timeout like any other transient failure.
Down entirely. Everything that is not a sandbox still works, which includes sign-in, configuration and past logs. Readiness deliberately leaves Sprites out, so a pod does not go NotReady over a third party.

What a replacement must provide

Here is the checklist. It needs the ten operations above and bearer auth. It needs name-keyed idempotent create and destroy, with a 409 on a duplicate and a delete that tolerates a 404. It needs the stream-id frame protocol with a real exit frame, and detachable sessions that replay from the start. It needs a network policy that can deny, and has_more and next_continuation_token pagination.

Get those semantics right, and the four subtle ones above with them. SPRITES_BASE_URL is then the only thing that changes.