Streaming from the sandbox without the API in the middle
In January 2026 a Sukuna chat was a browser holding one long response open against the Django backend. The agent ran in a backend worker and wrote its messages to Postgres. The stream endpoint read the table, sent what was new, slept half a second, and read again. By 23 April the backend’s proxy module was deleted and the browser read events from the sandbox the agent ran in. This is how the path moved, as the commits show it.
The timeline
| Date | What changed |
|---|---|
| 2 Sep 2025 | Streaming is a WebSocket, an AgentStreamConsumer on Django Channels in the backend |
| 19 Jan 2026 | WebSockets replaced by SSE. The backend endpoint polls the database and honours Last-Event-ID |
| 21 Feb | The agent server starts running inside the sandbox, with its own GET /runs/{id}/stream |
| 24 Feb | The backend’s agent views become a proxy. The stream is relayed line by line |
| 9 Mar | The sandbox gets /runs/{id}/stream/direct behind a backend-minted JWT. The browser tries it first and falls back to the proxy |
| 26 Mar | The sandbox server is rewritten on Django. JWT auth is deleted and restored the same day |
| 7 and 8 Apr | The direct URL is fixed for local mode, then switched off for local mode |
| 13 Apr | The backend’s relay endpoint is removed. The sandbox gets CORS headers and a stream read from its database |
| 23 Apr | The backend proxy module is deleted. One call hands the browser a sandbox host and a token |
The relay
On 21 February the agent server went into the sandbox image. On 24 February the backend’s agent views were rewritten around a 101-line proxy.py. This was the stream half of it:
async with httpx.AsyncClient(timeout=timeout) as client:
async with client.stream("GET", url, headers=_default_headers()) as resp:
resp.raise_for_status()
async for line in resp.aiter_lines():
yield line + "\n"
The read timeout on that client was 600 seconds. The header was one static API key held by the backend, which the browser never saw. Each open chat cost the backend a held response and an upstream connection for as long as the run lasted.
The first direct path
On 9 March two commits landed together, one in the sandbox repo and one in the backend. The sandbox gained a 192-line stream_auth.py and a new route beside the old one. The README I wrote that day calls the old route the “legacy proxied stream path” and lists what a token for the new one must carry: issuer, audience, sub equal to the run id in the path, a conversation id, a user id, a scope containing stream:read, and exp, iat and jti. An expired or invalid token got a 401. A token for a different run got a 403. Eight tests in two files pinned those cases, one of them named test_direct_stream_rejects_wrong_run_token.
The backend minted the token as HS256 with a 120 second default and returned it from the start call with a URL and an expiry. The frontend built a list of two targets, direct then proxy. If the direct one failed it showed a toast, “Direct stream unavailable (reason), falling back to proxy stream”, and carried on.
The same sandbox commit added the channel in the other direction. Callbacks for run start, periodic usage and the terminal state went from the sandbox to the backend through an outbox with retries, each signed with HMAC-SHA256 over the timestamp and the raw body. Lease limits on runtime, tokens and cost were enforced inside the sandbox, each with its own error code.
What the rewrite dropped
On 26 March I rewrote the sandbox server from FastAPI and SQLAlchemy to Django Ninja and the Django ORM, pointed at the same Postgres as the backend. The sandbox now wrote run state into the backend’s tables itself (the module is infra/sync.py), so the callbacks had no job. One backend commit that day removed 1,627 lines of webhook endpoints, HMAC checks and processing.
The rewrite’s own commit message says it “deletes all JWT stream auth”. A later commit the same day is titled “restore JWT auth for direct streaming”. What came back was 66 lines on PyJWT, and it is what the public repo still has in auth.py:
return {
"type": "jwt_stream",
"user_id": claims.get("user_id"),
"run_id": claims.get("sub"),
"conversation_id": claims.get("conversation_id"),
"scope": scope,
}
sub is required and returned. Nothing reads it afterwards. stream_run checks the scope and that the run exists. The 403 for a wrong-run token did not survive the rewrite, and the tests that pinned it had stayed behind in the old sandbox repo when the code was imported into the monorepo on 9 March.
The second thing dropped was CORS. The FastAPI server had allowed every origin. The Django settings file that replaced it read MIDDLEWARE = [] under the comment “Minimal, no middleware stack”. On 7 April I fixed the direct URL so it worked in local mode. On 8 April I turned the direct URL off for local mode, with a comment that the local agent server sent no CORS headers and the browser would block the fetch. The same commit fixed the frontend’s fallback, which had been wiping the loaded conversation whenever the direct attempt failed before its first event.
Removing the fallback
In the commit of 13 April the sandbox settings got CORS back, this time with the argument written down in settings.py:
# CORS preflight. This is safe because: (1) each sandbox serves one
# conversation, (2) all endpoints require JWT validation, (3) no cookie auth.
CORS_ALLOW_ALL_ORIGINS = True
CORS_ALLOW_CREDENTIALS = False
The same commit removed the backend’s relay endpoint and its 856-line streaming module, and changed how the sandbox served the stream. Until then a live run was served from an in-process bus that replayed its history to each subscriber. After it the stream reads only the events table. The row’s sequence number is the SSE id, and a client resumes with ?after= or Last-Event-ID. A frontend regression test added that day has two cases: stop retrying after an unrecoverable 401 on the direct stream, and stop a reconnect loop when responses keep ending without progress.
The commit of 23 April removes proxy.py, 226 lines by then, with 973 lines of tests. Starting a run, cancel, approvals and MCP calls had gone through it too. In its place the backend has one call, POST /chat/sandbox/acquire, which provisions the sandbox and returns its host, a token and an expiry. The frontend store refreshes the token 30 seconds before it expires, or when the sandbox answers 401.
The token widened to match. In mint_direct_stream_token it now carries five scopes, and when no run exists yet its sub is the conversation id. A require_scope decorator on each sandbox route checks the scope.
Two days later, on the branch for the developer API, a relay came back as an optional endpoint for clients holding an API key. Its commit message says the direct path “remains the recommended path” for browsers.
Where it ended up
The later sandbox is public as sukuna-sandbox. It is published as a single commit, so the steps between are not in this account. Its tokens are EdDSA. Outside local development the sandbox holds only public keys. The check the March rewrite lost is back in backends/sandbox/auth.py, next to one that did not exist before:
if claims.sub != context.run_id:
_raise_failure(CapabilityJwtAuthCode.WRONG_RUN, "capability token run mismatch")
expected_sandbox_id = self._config.sandbox_id or read_e2b_sandbox_id()
if claims.sandbox_id != expected_sandbox_id:
_raise_failure(CapabilityJwtAuthCode.WRONG_SANDBOX, "capability token sandbox mismatch")
The limits of the public Sukuna version
The token is HS256, and the backend puts the signing secret in the sandbox’s environment so the sandbox can verify. Anything that can read that environment can mint a token, and the agent runs there. Nothing ties the token to the run in the path, so for its 120 seconds it is good for whatever that sandbox serves, within its five scopes. CORS is open to every origin, so the token is the only gate.
What I would do differently
Carry the tests across before the server. The wrong-run check had a test on 9 March and was gone on 26 March, and no test failed because the tests were in another repo.
Write the CORS argument down the first time. The setting went in a rewrite and stayed out for 18 days, with the proxy fallback still in place.
Delete the fallback sooner. From 9 March to 13 April the browser had two transports, and two of the fixes in that stretch were to the seam between them.