Running commands

Run a command and wait, stream its output, or start it in the background.

curl -X POST https://agental.io/v1/sandboxes/{id}/exec \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":["sh","-c","cd /opt/agental && npm test"],"timeoutMs":90000}'

• command is a list of arguments, not a line of shell. For pipes, &&, redirects or variables, pass ["sh","-c","..."].
• The answer is HTTP 200 with exitCode, stdout, stderr and truncated, even when the command fails.

Environment#

Every command starts fresh: as root, in /root, with an environment that holds PATH and little else. A cd or export does not carry over. Begin each command with cd /opt/agental, and set HOME=/root when a tool asks for it. What is on that PATH is in Languages and tools.

The variables of the sandbox's template and its own are there too, and three that agental gives every command, so that a program or an agent in the machine can name its own sandbox in a call to the API and move its stop:

• A template or a sandbox cannot hold a variable of any of these names: setting one answers 400 invalid_request.
• What a command starts has them as well, as a coding agent run with exec does. A shell that logs in, over SSH or by su -, has them from the machine's /etc/environment, which agental writes as the sandbox is made, forked or started and as SSH is turned on. A fork's shells name the fork, not its source.
• A variable kept out of the sandbox holds its stand-in, agental_hidden_ and 32 letters and digits, in place of its value.

Timeouts and output#

Streaming#

Same body. Answers with server-sent events: stdout and stderr events carrying {"data":"..."}, then one exit event carrying {"exitCode":0}. A stream that fails ends with an error event that says why, and no exit event.

Background work#

A proxy in front of the API stops waiting for an answer after 100 seconds, so /exec takes a timeoutMs of up to 90000, and refuses a larger one with 400. No command may run longer than 10 minutes. For servers and long builds, start the process in the background inside the machine and return at once:

{"command":["sh","-c","cd /opt/agental && nohup npm run dev > dev.log 2>&1 < /dev/null &"]}

Check on it with ordinary commands such as tail -n 50 dev.log or pgrep -f "npm run dev".

Takes the same body, with timeoutMs up to 600000, and answers at once with an id. Use it for anything that may take longer than 90 seconds. GET /v1/sandboxes/{id}/commands/{commandId} returns its status (running, succeeded, failed or timed_out), its exitCode and its output so far.

To run a command again and again, every so often or at a time of day, give it a schedule: the sandbox is started for each run when it is stopped.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]