Skip to Content
AI

Agent sandbox automatic runs

Automatic Kenso sandbox runs: Kenso starts an opted-in person's sandbox when the workspace's work for its own agent has waited long enough, one sandbox at a time per workspace, the person whose sandbox ran longest ago first, within the workspace's monthly cap. Each person opts in per workspace; the cap and the wait are the workspace's. Behind the agent_work and agent_sandboxes features, never open to a Client seat or a scoped API key.

AI3 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. 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-Idheaderinteger (int64)optionalThe 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.

Get the automatic run settings

GET/v1/agent-sandbox/auto-run-settingsagent-sandbox-auto-run-settings.get
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key
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

Your own switch and agent in this workspace, and the workspace's monthly cap and wait. Nothing saved reads as enabled false, agent null, monthlyCapCredits 0 (no automatic run starts) and waitMinutes 60.

Errors:

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

Open to any workspace member except a Client seat, and never to an API key held to a permission template.

Request
curl -X GET "https://api.ken.so/v1/agent-sandbox/auto-run-settings" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a AgentSandboxAutoRunSettings.

Show the 4 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Turn your own automatic runs on or off

PATCH/v1/agent-sandbox/auto-run-settingsagent-sandbox-auto-run-settings.update
Permission
Any workspace member except a Network member
Rate limit
4,800 requests a minute per API key
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

Body: { "enabled": true, "agent": "codex" }, either or both. agent is claude, codex, antigravity, opencode, grok or cursor. Turning on, or changing the agent while on, needs that agent connected in your Kenso sandbox; turning off always succeeds. Automatic runs spend the workspace's credits within its monthly cap. Returns the settings as the GET does.

Errors:

  • 400 validation_failed: an empty body, an unknown agent, or on with no agent picked.
  • 404 not_found: a feature is off, or the credential is not a person's.
  • 409 agent_not_connected: connect the agent in your Kenso sandbox first.

Open to any workspace member except a Client seat, and never to an API key held to a permission template.

Request body

application/json, optional.

FieldTypeRequiredDescription
enabledbooleanoptionalTurn your automatic runs in this workspace on or off.
agentstringoptionalThe agent Kenso starts: claude, codex, antigravity, opencode, grok or cursor. It must be connected to turn on.
Request
curl -X PATCH "https://api.ken.so/v1/agent-sandbox/auto-run-settings" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "agent": "string"
}'

Response 200

data is a AgentSandboxAutoRunSettings.

Show the 4 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Set the workspace's monthly cap and wait

PATCH/v1/agent-sandbox/auto-run-settings/workspaceagent-sandbox-auto-run-settings.update-workspace
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key
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

Body: { "monthlyCapCredits": 2000, "waitMinutes": 30 }, either or both. The cap counts what automatic runs charged in the calendar month (UTC); a manual run does not count. 0 starts none. The wait is how long work waits for the workspace's own agent before Kenso starts a sandbox. Returns the settings as the GET does.

Errors:

  • 400 validation_failed: an empty body, monthlyCapCredits outside 0 to 100000, or waitMinutes outside 15 to 1440.
  • 403 forbidden: the workspace_settings permission is missing.
  • 404 not_found: a feature is off, or the credential is not a person's.

Requires the workspace_settings permission. Never open to a Client seat or an API key held to a permission template.

Request body

application/json, optional.

FieldTypeRequiredDescription
monthlyCapCreditsinteger (int32)optionalCredits automatic runs may charge in a calendar month (UTC), 0 to 100000. 0: none start.
waitMinutesinteger (int32)optionalMinutes work waits before Kenso starts a sandbox, 15 to 1440.
Request
curl -X PATCH "https://api.ken.so/v1/agent-sandbox/auto-run-settings/workspace" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "monthlyCapCredits": 1,
  "waitMinutes": 1
}'

Response 200

data is a AgentSandboxAutoRunSettings.

Show the 4 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page