Skip to main content
A harness session runs a coding harness, such as Claude Code, Codex, or OpenCode, in its own sandbox on your Nasiko cluster. You open a session, then chat in it. The sandbox starts on the first message, and it can be suspended between turns and resumed later. These routes aren’t in the generated OpenAPI spec. CLI: nasiko harnesses and nasiko session new|show|ls|suspend|rm. See Chat commands.
Harness sessions are off by default. The server operator turns them on with HARNESS_SESSIONS_ENABLED=true. While they’re off, GET /api/harnesses returns an empty list and POST /api/sessions returns 403 with the code harness_sessions_disabled.

Authentication and errors

Every route takes a session JWT in Authorization: Bearer <token> (from POST /api/auth/login) or the dashboard cookie. A missing or expired token returns 401. Any signed-in user can open sessions. Each session belongs to the user who opened it. Errors are JSON:

The session object

List harnesses

GET /api/harnesses The harnesses enabled on this server. Matches nasiko harnesses.
Response 200 OK
The list is never paged. Use id as harness when you open a session.

Open a session

POST /api/sessions Creates a session on a harness. No sandbox starts yet: the session is parked until you send its first message. Matches nasiko session new. Request body
Response 201 Created
Each call opens a new session. The request isn’t idempotent. Errors: invalid_repo, unknown_harness, harness_sessions_disabled, harness_not_ready. A server can also refuse a session with its own status and { "error", "code" } body, for example when a plan limit is reached.

Chat in a session

Send A2A message/send or message/stream requests to POST /api/agents/{agent_id}, with the session’s session_id as params.message.contextId. The first message starts the sandbox. See Call a deployed agent. From the CLI, use nasiko chat --session <id> "message". Only the session’s owner can chat in it. A message under someone else’s session ID returns 404. When the server refuses a turn, for example because harness sessions are off, the response is 200 with a JSON-RPC error. Its code is -32610, and its data is the same { "error", "code" } body that POST /api/sessions returns.

Get a session

GET /api/sessions/{id} Response 200 OK: { "data": <session> }. Returns session_not_found when the session doesn’t exist or belongs to someone else. Matches nasiko session show.

List sessions

GET /api/sessions Your harness sessions, most recently active first: by last turn, or by creation time for a session with no turns. Matches nasiko session ls.
Response 200 OK
Pass next_cursor back as cursor until has_more is false. Cursors are opaque. Paging is forward only.

Suspend a session

POST /api/sessions/{id}/suspend Stops the session’s sandbox and keeps the session, which frees an idle sandbox. The next message resumes it. Matches nasiko session suspend.

Delete a session

DELETE /api/sessions/{id} Releases the session’s sandbox and removes the session. The sandbox’s credentials are revoked with it. A superuser can delete any user’s session. Matches nasiko session rm. Response 204 No Content. Errors: session_busy (409) while a turn is running, and session_not_found (404). Deleting a session through DELETE /api/chat/sessions/{id} also releases its sandbox.