Commands

A command is one program run in a Sandbox, called an Execution in the API. Ortam accepts each command once and gives it a stable ID, then runs it, observes it and keeps its record after it ends. Disconnecting never cancels it.

Running one

Send the command to its Sandbox. A stopped Sandbox starts first. The response is 202: the command is accepted and has an ID, and it runs in the background.

Shell

curl -X POST "$ORTAM_API/v1/sandboxes/$SANDBOX_ID/executions" \
  -H "Authorization: Bearer $ORTAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"argv": ["/bin/bash", "-lc", "npm test"], "timeout_seconds": 900}'

Read it by its ID until it has a result. The record stays readable after the command ends, after you disconnect and after the Sandbox stops.

Shell

curl "$ORTAM_API/v1/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $ORTAM_API_KEY"

Run a command in the API reference lists every field and the records it returns.

Inputs

argv: The program and its arguments, run exactly as given. For shell syntax, run a shell: ["/bin/bash", "-lc", "npm ci && npm test"].
cwd: The working directory. Defaults to /home/developer.
env: Environment variables. They override the Sandbox’s defaults with the same names.
timeout_seconds: Optional; without it there’s no timeout. Counts from launch, not while the Sandbox is starting. When it passes, only this command’s processes are asked to end.
connection_id: The Connection the command uses. Defaults to the Sandbox’s default Connection.

Inputs are fixed when the command is accepted. Changing the Sandbox’s settings later affects only commands accepted after that. Secret inputs aren’t returned when you read the command back, but arguments, files and output aren’t filtered for secrets.

States

A command’s state is one of these:

accepted: Ortam accepted it and hasn’t launched it yet, for example while the Sandbox starts.
running: The program is running.
exited: The program ended, and exit_code holds its code. A nonzero code is your program’s result, not an Ortam failure.
not_launched: It was accepted but never started, for example because the Sandbox stopped first.
launch_failed: Starting the program failed, such as a missing executable or working directory.
timed_out: The timeout passed and Ortam asked the command’s processes to end.
resource_exhausted: The command ran out of a resource it needed.
interrupted: You or a Stop asked it to end.
infrastructure_lost: The host failed while it ran.
unknown: Ortam can’t establish what happened. It never reruns the command on its own.

Whether the processes a command started have ended is reported separately from its result. An exit code doesn’t prove that background processes ended, and services the command started can keep running until the Sandbox stops.

Interrupting and output

Interrupting asks the command’s tracked processes to end, including ones left behind after it exited or after an unknown outcome. It doesn’t stop the Sandbox or undo anything the command did outside it.

Results and output stay readable after the Sandbox stops. Output keeps its position, so a reader can reconnect and continue. The part already kept is marked; the newest lines can be lost if the host fails, and gaps, truncation at [output limit] per stream and expiry after [output retention] are marked too. Kept output doesn’t mean the files were saved.