Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
sandbox
/
bash
Sandbox: Bash
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/sandbox/bash \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "command": "ls -la",
  "timeout": 300,
  "working_dir": ""
}
'
{
  "status": "ok",
  "stdout": "<string>",
  "stderr": "<string>",
  "exit_code": 123,
  "content": "<string>",
  "path": "<string>",
  "matches": [
    {}
  ],
  "url": "<string>",
  "error": "<string>"
}
Run a shell command inside the per-agent sandbox.

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

​
command
string
required
Shell command to execute inside the sandbox.
​
timeout
integer
default:300
Maximum execution time in seconds before the command is terminated.
​
working_dir
string
Optional working directory for the command. Defaults to the sandbox root when empty.

​
Response

​
status
string
Result status of the operation (e.g., ok).
​
stdout
string
Standard output captured from the command.
​
stderr
string
Standard error captured from the command.
​
exit_code
integer
Process exit code.

​
Example Request

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/sandbox/bash" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "command": "ls -la",
    "timeout": 300,
    "working_dir": ""
  }'

​
Notes

  • The sandbox is per-agent and persists between calls, so files created here remain available to subsequent sandbox operations for the same agent.
  • Commands are run as an unprivileged user. Avoid commands that require elevated permissions.

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Agent UUID

Body

application/json

Request body for running a bash command inside the agent sandbox.

​
command
string
required

Shell command to execute inside the sandbox.

Example:

"ls -la"

​
timeout
integer
default:300

Maximum execution time in seconds before the command is terminated.

Required range: x >= 1
​
working_dir
string
default:""

Optional working directory for the command. Defaults to the sandbox root when empty.

Response

Successful Response

Generic response wrapper returned by agent sandbox endpoints. Not every field is populated for every tool.

​
status
string

Result status of the sandbox operation.

Example:

"ok"

​
stdout
string | null

Standard output captured from the sandbox command. Present for bash.

​
stderr
string | null

Standard error captured from the sandbox command. Present for bash.

​
exit_code
integer | null

Process exit code returned by the sandbox. Present for bash.

​
content
string | null

File contents. Present for file_read.

​
path
string | null

File path affected by the operation. Present for file_write, file_edit, multi_edit, file_share.

​
matches
Matches · object[] | null

Match results. Present for glob and grep.

​
url
string<uri> | null

Public CDN URL. Present for file_share.

​
error
string | null

Error message when the operation fails.