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.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | 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. 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-Id | 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. |
Get the automatic run settings
/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
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.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.
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
/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
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.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.
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | optional | Turn your automatic runs in this workspace on or off. |
agent | string | optional | The agent Kenso starts: claude, codex, antigravity, opencode, grok or cursor. It must be connected to turn on. |
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
/v1/agent-sandbox/auto-run-settings/workspaceagent-sandbox-auto-run-settings.update-workspace- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
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.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,monthlyCapCreditsoutside 0 to 100000, orwaitMinutesoutside 15 to 1440.403 forbidden: theworkspace_settingspermission 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.
| Field | Type | Required | Description |
|---|---|---|---|
monthlyCapCredits | integer (int32) | optional | Credits automatic runs may charge in a calendar month (UTC), 0 to 100000. 0: none start. |
waitMinutes | integer (int32) | optional | Minutes work waits before Kenso starts a sandbox, 15 to 1440. |
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.
More in AI:AI runsAI linesAI line holdsAutonomous repliesAgent work settingsAgent permissionsAgent workAgent sandbox connectionsAgent sandbox runsAI feedbackAll resources