> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness sessions API

> List coding harnesses, and open, inspect, suspend, and delete sessions that run one in a sandbox.

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](https://docs.nasiko.com/reference/cli/chat.md).

> [!NOTE]
>
> 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:

```json theme={null}
{ "error": "session not found", "code": "session_not_found" }
```

| Code | Status | Meaning |
| - | - | - |
| `invalid_repo` | `400` | `repo` failed validation. The `error` says why |
| `unknown_harness` | `400` | The harness doesn't exist or is disabled |
| `invalid_parameter` | `400` | A query parameter is out of range or malformed |
| `harness_sessions_disabled` | `403` | Harness sessions are off on this server |
| `forbidden` | `403` | You asked for another user's sessions without being a superuser |
| `session_not_found` | `404` | No such session, or it isn't yours |
| `session_busy` | `409` | A turn is running on the session |
| `sandbox_error` | `502` | The sandbox provider failed |
| `harness_not_ready` | `503` | The harness's agent isn't registered on the server yet. Retry shortly |
| `internal_error` | `500` | Server error |

## The session object

```json theme={null}
{
  "session_id": "0f9e8d7c-6b5a-4f3e-9d2c-1b0a9f8e7d6c",
  "harness": "claude-code",
  "agent_id": "a7b6c5d4-e3f2-4a1b-9c8d-7e6f5a4b3c2d",
  "runtime_state": "parked",
  "sandbox_ref": null,
  "last_turn_at": null,
  "suspended_at": null,
  "workspace_repo": "https://github.com/acme/app.git"
}
```

| Field | Description |
| - | - |
| `session_id` | Session ID. It's also the A2A `contextId` you chat with |
| `harness` | Harness ID |
| `agent_id` | The harness agent the session runs on. Send messages to `POST /api/agents/{agent_id}` |
| `runtime_state` | `parked` (no sandbox running), `starting`, `running`, or `stopping` |
| `sandbox_ref` | The session's sandbox, once one has been created |
| `last_turn_at` | When the last turn ran |
| `suspended_at` | When the sandbox was last suspended |
| `workspace_repo` | Repository cloned into the session's workspace, or `null` |

## List harnesses

`GET /api/harnesses`

The harnesses enabled on this server. Matches `nasiko harnesses`.

```bash theme={null}
curl https://nasiko.example.com/api/harnesses \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    { "id": "claude-code", "name": "Claude Code", "image": "nasiko/harness-claude-code:0.1.0", "protocol_version": 1, "enabled": true },
    { "id": "codex", "name": "Codex", "image": "nasiko/harness-codex:0.1.0", "protocol_version": 1, "enabled": true },
    { "id": "opencode", "name": "OpenCode", "image": "nasiko/harness-opencode:0.1.0", "protocol_version": 1, "enabled": true }
  ],
  "has_more": false,
  "next_cursor": null,
  "prev_cursor": null
}
```

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**

| Field | Type | Required | Description |
| - | - | - | - |
| `harness` | string | Yes | Harness ID from `GET /api/harnesses` |
| `repo` | string | No | Repository to clone into the workspace. Must be an `https://` or `ssh://` URL on a host the server allows, up to 2,048 characters, with no credentials in the URL. For SSH, use `ssh://git@host/org/repo.git`, not the `git@host:org/repo.git` form |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/sessions \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"harness": "claude-code", "repo": "https://github.com/acme/app.git"}'
```

**Response** `201 Created`

```json theme={null}
{ "data": { "session_id": "0f9e8d7c-...", "harness": "claude-code", "runtime_state": "parked", "...": "..." } }
```

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](https://docs.nasiko.com/api-reference/chat.md#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}`

| Path parameter | Description |
| - | - |
| `id` | Session 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`.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `harness` | string | | Only sessions on this harness |
| `state` | string | | Only sessions in this state: `parked`, `starting`, `running`, or `stopping` |
| `limit` | integer | `50` | Page size, `1` to `200` |
| `cursor` | string | | `next_cursor` from the previous page |
| `user_id` | UUID | | Superusers only: list this user's sessions |

```bash theme={null}
curl "https://nasiko.example.com/api/sessions?harness=claude-code&limit=20" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [ { "session_id": "0f9e8d7c-...", "runtime_state": "running", "...": "..." } ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMS0xNFQwOToxMjowMy40MTIwMDBafDBmOWU4ZDdj",
  "prev_cursor": null
}
```

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`.

```bash theme={null}
curl -X POST https://nasiko.example.com/api/sessions/0f9e8d7c-6b5a-4f3e-9d2c-1b0a9f8e7d6c/suspend \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

| Status | Meaning |
| - | - |
| `204 No Content` | The sandbox is suspended, or there was nothing to suspend. Safe to repeat |
| `202 Accepted` | Suspension is in progress. The body is `{ "data": { "status": "suspending" } }`. Poll `GET /api/sessions/{id}` until `runtime_state` is `parked` |
| `409` `session_busy` | A turn is running. Wait for it to finish, then retry |
| `404` `session_not_found` | No such session, or it isn't yours |
| `502` `sandbox_error` | The sandbox provider failed |

## 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}`](https://docs.nasiko.com/api-reference/chat#delete-a-chat-session) also releases its sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.