Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
workspace
/
bash
Workspace: Bash
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/workspace/bash \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "command": "<string>",
  "timeout": 300,
  "working_dir": ""
}
'
{
  "stdout": "",
  "stderr": "",
  "exit_code": 0,
  "duration": 0
}
Run a shell command inside the per-agent workspace.

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

​
command
string
required
Shell command to execute inside the workspace.
​
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 workspace 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>/workspace/bash" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "command": "ls -la",
    "timeout": 300,
    "working_dir": ""
  }'

​
Notes

  • The workspace is per-agent and persists between calls, so files created here remain available to subsequent workspace 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

Body

application/json
​
command
string
required

Shell command to execute inside the workspace. Supports installing packages (apt-get, pip, npm), running scripts, and general shell operations.

Example:

"pip install pandas && python -c 'import pandas; print(pandas.__version__)'"

​
timeout
integer
default:300

Maximum execution time in seconds. The command is killed if it exceeds this limit.

Required range: 1 <= x <= 1800
Example:

60

​
working_dir
string
default:""

Working directory for the command, relative to workspace root. Defaults to the workspace root.

Example:

"my_project"

Response

Successful Response

​
stdout
string
default:""

Standard output captured from the command

Example:

"2.2.0\n"

​
stderr
string
default:""

Standard error captured from the command

Example:

""

​
exit_code
integer
default:0

Process exit code. 0 indicates success, non-zero indicates failure.

Example:

0

​
duration
number
default:0

Execution duration in seconds

Example:

3.21