Run a command
curl --request POST \
--url 'http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"command":"echo hello"}'import requests
url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell"
payload = { "command": "echo hello" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({command: 'echo hello'})
};
fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"exit_code": 0,
"stdout": "hello\n",
"stderr": "",
"decision": null,
"line_id": "line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37"
}
Shell
Run shell command
POST
/
v1
/
workspaces
/
{workspace_id}
/
shell
Run a command
curl --request POST \
--url 'http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"command":"echo hello"}'import requests
url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell"
payload = { "command": "echo hello" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({command: 'echo hello'})
};
fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"exit_code": 0,
"stdout": "hello\n",
"stderr": "",
"decision": null,
"line_id": "line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37"
}
Run a shell command or script in the workspace and return its exit code and output.
One endpoint serves three modes:
A
See error examples and recovery steps. The complete OpenAPI contract includes every response schema.
| Mode | Request | Response |
|---|---|---|
| Run (default) | no query flags | One JSON result when the command ends. |
| Stream | stream=true | NDJSON output records as they are produced, then a status record. |
| Explain | explain=true | The policy decision. Nothing runs. |
200 means the request was accepted, not that the command succeeded. Check exit_code. A policy refusal also returns 200; check decision to know whether a policy refused anything. See Refused commands below.
The request stays open until the command ends, and closing it cancels the command. To leave work running, end the command with &; it returns at once and the work appears under jobs. Every result carries a line_id for the lines endpoints.
To send input, use a multipart/form-data body with a stdin part, or set open_stdin=true with stream=true to write while the command runs. See Streaming and stdin.
Stream output
Setstream=true to receive output as it is produced. Each line is one JSON record: output records carry base64 data, and the last record carries status and the final result.
curl --no-buffer --request POST \
--url 'http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell?stream=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"command":"echo hello"}'
{"stream":"stdout","data":"aGVsbG8K"}
{"status":"done","result":{"exit_code":0,"stdout":"","stderr":"","decision":null,"line_id":"line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37"},"error":null}
Explain a command
Setexplain=true to get the policy decision without running the command. The response has one node per part of the line; the example below is trimmed to one command.
curl --request POST \
--url 'http://127.0.0.1:8765/v1/workspaces/{workspace_id}/shell?explain=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"command":"echo hello"}'
{
"line": "echo hello",
"outcome": "allow",
"reason": "",
"decision": null,
"exit_code": 0,
"node": {
"type": "line",
"text": "echo hello",
"children": [
{
"type": "command",
"text": "echo hello",
"command": "echo",
"outcome": "allow",
"children": []
}
]
}
}
Refused commands
A policy refusal returns200. decision is set whenever a policy refused something on the line, and is null otherwise. The exit code alone does not tell you:
- A command refused before it runs usually exits
126with<command>: Permission denied. - A refusal about a path appears as that path’s own error, such as exit
1. - A policy that judges a command after it ran sets exit
126but does not undo its effects, and output already sent stays sent. A policy that judges the whole line after it ran drops the line’s output. - A pipeline exits with its last stage’s status unless
pipefailis set, so a refused earlier stage can leave the exit code at0.
{
"exit_code": 126,
"stdout": "",
"stderr": "rm: Permission denied\n",
"decision": {
"kind": "deny",
"reason": "rm is not allowed in this workspace",
"policy": "PermissionsPolicy",
"ask_id": null,
"matched": {
"command": ["rm"],
"flags": [],
"keys": []
}
},
"line_id": "line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c38"
}
Keep stdin open
Withstream=true and "open_stdin": true, the first record carries the line_id, and you write input to that line while the command runs. See Streaming and stdin for the full flow.
{
"exit_code": 0,
"stdout": "hello\n",
"stderr": "",
"decision": null,
"line_id": "line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37"
}
Errors
Errors
| Status | Meaning |
|---|---|
400 | The request is malformed or its options conflict. The body is not JSON (invalid_json), a field is missing, unknown or of the wrong type (missing_field, unknown_field, invalid_value, with param; a field of the multipart request part is named as in a JSON body), or machine names one the workspace does not have (invalid_value, param machine), refused before anything runs. Or the multipart parts are malformed, missing or out of order, or the options conflict, as stream with explain, open_stdin without stream=true or with a stdin part, or explain with a multipart body, cwd, machine or open_stdin set to true (invalid_request). |
401 | The token is missing or wrong (unauthorized). |
404 | The workspace, session, job, file or route does not exist, or the caller may not see it (not_found). |
409 | Another server owns command execution for this workspace (workspace_busy; the message names that server), or the workspace is stopped (workspace_stopped). |
429 | Past a rate limit (rate_limited), or a new session past max_sessions (session_limit). |
413 | The request body, a multipart part, or stdin exceeds its size limit (too_large). |
499 | The running shell job was canceled (canceled). |
500 | The command’s job failed internally (internal). The message is always internal server error. The job’s own error stays readable as error at GET /v1/workspaces/{workspace_id}/lines/{line_id}, and in a stream’s final record. |
503 | The server is shutting down and accepts no new commands (shutting_down). |
Authorizations
Query Parameters
Return the policy decision for the command without running it. Only command is evaluated; record is ignored and open_stdin may be false. A multipart body, a body that sets cwd or machine (an empty string counts as set, null does not), or open_stdin set to true, is rejected with 400. Cannot be combined with stream.
Body
application/jsonmultipart/form-data
Response
The request was accepted. By default the body is one JSON result. With explain=true it is the policy decision and nothing ran. With stream=true it is NDJSON. A 200 does not mean the command succeeded; check exit_code.
- Result
- Explanation (explain=true)
Returned by default, when the command has ended.