Sessions

A session is a managed, named command running inside a sandbox — distinct from a one-shot exec call. Sessions are tracked server-side by name, so you can list them, attach to their output, and kill them independently of the connection that created them.

Sessions are one of three ways to run commands in a sandbox. For a synchronous, buffered command or an unnamed interactive TTY, see Exec.

Identity

A session is scoped to a sandbox_id and keyed by session_name, which must match ^[a-z][a-z0-9-]{0,31}$ — lowercase, starting with a letter, up to 32 characters. There’s no separate session ID; the name is the identifier within its sandbox.

Creating a session

curl -s -X POST "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/sessions" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "dev", "cmd": ["npm", "run", "dev"]}'

bonya session create $SANDBOX_ID dev -- npm run dev

const info = await sandbox.createSession("dev", ["npm", "run", "dev"]);

info = sandbox.create_session("dev", ["npm", "run", "dev"])

info, err := sandbox.CreateSession(ctx, "dev", []string{"npm", "run", "dev"})

MCP: the session_create tool covers this. The request body extends the common command shape (cmd, env, path) with session-specific fields:

string

required

Session name. Must match ^[a-z][a-z0-9-]{0,31}$.

string[]

required

Argv to run. At least one element.

object

Environment variables to set.

string

Working directory.

integer

Terminal width, 1–512.

integer

Terminal height, 1–512.

boolean

default:"false"

Whether to replace an existing session of the same name.

A successful create returns 201 with { "session": { ...SessionInfo } }.

Name collisions

Creating a session whose name collides with a live (non-terminal) session returns 409 session_exists. replace: true only takes effect against a session that has already reached a terminal state (EXITED, KILLED, or FAILED) — it does not let you forcibly replace a session that’s still running or attached. To replace a running session, kill it first, then create.

Session state

Each SessionInfo reports:

string

required

The session name.

string[]

required

The argv the session was started with.

string

required

The session’s working directory.

string

required

One of UNSPECIFIED, STARTING, IDLE, ATTACHED, EXITED, KILLED, FAILED.

boolean

required

Whether a client is currently attached.

integer

required

Start time.

integer

required

Last observed activity.

integer

End time, once the session has reached a terminal state.

object

{ exit_code, signaled, signal }, present once the session has exited.

EXITED, KILLED, and FAILED are the terminal states referenced above under name collisions; STARTING, IDLE, and ATTACHED are all live.

Sessions and suspension

A session’s process never blocks idle suspend by itself. Only an attached client does, for as long as it stays connected — a quiet, detached session lets the sandbox warm-suspend on its normal idle schedule, and survives the resume with its process and replay buffer intact, the same session rather than a new one. Output the session keeps producing while detached still counts as activity and defers idle suspend on its own. Attaching to a session on a suspended sandbox wakes it, the same way exec traffic does — see Sandboxes for the resume path.

Listing sessions

curl -s "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/sessions" \
  -H "Authorization: Bearer $BONYA_API_KEY"

bonya session list $SANDBOX_ID

for (const info of await sandbox.listSessions()) {
  console.log(info.name, info.status);
}

for info in sandbox.list_sessions():
    print(info.name, info.status)

result, err := sandbox.ListSessions(ctx)
for _, info := range result.Sessions {
    fmt.Println(info.Name, info.Status)
}

MCP: the session_list tool covers this. Returns SessionListResponse:

SessionInfo[]

required

All sessions tracked for the sandbox.

boolean

required

Whether the sandbox was suspended when this list was produced.

Listing sessions never wakes a suspended sandbox. If the sandbox is suspended, the response answers from a snapshot of session state taken at suspend time, and sandbox_suspended is true — it does not resume the sandbox to get a live answer. To act on the sessions themselves, resume the sandbox first (see Sandboxes).

Attaching to a session

GET /v1/sandbox/{sandbox_id}/sessions/{session_name}/attach

This is a WebSocket upgrade — see WebSockets for how the upgrade, the START frame (AttachStartRequest), and admission work. Multiple clients can attach to the same session.

bonya session attach $SANDBOX_ID dev

const session = await sandbox.attachSession("dev");
for await (const event of session) {
  // ...
}
session.detach();

session = sandbox.attach_session("dev")
for event in session:
    ...
session.detach()

stream, err := sandbox.AttachSession(ctx, "dev")
for {
    event, err := stream.Next()
    if err != nil || event == nil {
        break
    }
}
stream.Detach()

There’s no cURL tab here since this operation has no JSON request/response shape to show — it’s a raw WebSocket upgrade, not a request/response call. For the same reason, there’s no session_attach MCP tool: an agent can start and stop background work via session_create/session_kill but can’t stream its live output.

Killing a session

curl -s -X POST "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/sessions/dev/kill" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "TERM", "grace_ms": 5000}'

bonya session kill $SANDBOX_ID dev

await sandbox.killSession("dev");

sandbox.kill_session("dev")

sandbox.KillSession(ctx, "dev")

MCP: the session_kill tool covers this, with signal and grace_ms fields matching the REST body. Request body (SessionKillRequest, optional):

string

default:"TERM"

One of TERM, KILL, INT, HUP.

integer

default:"5000"

Milliseconds to wait after the signal before the session is considered killed, 0–60000.

Returns 200 with { "session": { ...SessionInfo } } reflecting the signal having been delivered.

Get started

Tutorials

Core concepts

API essentials

Guides

Identity

Creating a session

Name collisions

Session state

Sessions and suspension

Listing sessions

Attaching to a session

Killing a session

Sandboxes

Exec

WebSockets

​Identity

​Creating a session

​Name collisions

​Session state

​Sessions and suspension

​Listing sessions

​Attaching to a session

​Killing a session

​Related

Sandboxes

Exec

WebSockets

Identity

Creating a session

Name collisions

Session state

Sessions and suspension

Listing sessions

Attaching to a session

Killing a session

Related