Agent sandbox connections

The Agent sandbox connections endpoints of the Kenso API.

2 endpointsKen-Version: 1.1Authentication Workspaces Errors

List your sandbox agent connections

GET/v1/agent-sandbox/connectionsagent-sandbox-connections.list

Needs the agent_sandboxes feature on your workspace. Until it is on, calls answer 404. Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Always six entries in data, in this order: claude, codex, antigravity, opencode, grok, cursor, each with status (connected or not_connected), connectedAt and lastRunAt. pagination.hasMore is always false. Your box serves every workspace you work in, so the list is the same in each.

Errors:

- 404 not_found: a feature is off, or the credential is not a person's.

Parameters

Name

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Response 200

data is a list of AgentSandboxConnection. Each item has these fields. The response also carries pagination.

Field

Type

Description

agent

string

claude, codex, antigravity, opencode, grok or cursor.

status

string

connected or not_connected.

connectedAt

string (date-time)

When the agent was first connected, or null while it is not connected.

lastRunAt

string (date-time)

When a sandbox run last used this agent, or null.

Request

curl -X GET "https://api.ken.so/v1/agent-sandbox/connections" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": [
    {
      "agent": "string",
      "status": "string",
      "connectedAt": "2026-09-23T15:02:11Z",
      "lastRunAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Disconnect an agent

DELETE/v1/agent-sandbox/connections/{agent}agent-sandbox-connections.disconnect

Needs the agent_sandboxes feature on your workspace. Until it is on, calls answer 404. Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Logs the agent CLI out in your Kenso sandbox and answers { agent, status: "not_connected" }. With no agent left connected, the sandbox itself is deleted. Disconnecting an agent that is not connected answers the same.

Errors:

- 400 validation_failed: an unknown agent. - 404 not_found: a feature is off, or the credential is not a person's. - 409 run_active: your sandbox is running a run. Stop it first. - 503 service_unavailable with Retry-After: the sandbox did not answer; try again.

Parameters

Name

Type

Required

Description

agent

In: path

string

required

The agent's id: claude, codex, antigravity, opencode, grok or cursor.

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Response 200

data is a AgentSandboxDisconnect.

Field

Type

Description

agent

string

The agent's id.

status

string

Always not_connected.

Request

curl -X DELETE "https://api.ken.so/v1/agent-sandbox/connections/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": {
    "agent": "string",
    "status": "string"
  }
}