Skip to main content
POST
Run a command
Run a shell command or script in the workspace and return its exit code and output. One endpoint serves three modes: A 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

Set stream=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.

Explain a command

Set explain=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.

Refused commands

A policy refusal returns 200. 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 126 with <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 126 but 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 pipefail is set, so a refused earlier stage can leave the exit code at 0.
A refusal does not always mean nothing ran, so do not retry a refused command blindly. A command denied before it ran:

Keep stdin open

With stream=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.
See error examples and recovery steps. The complete OpenAPI contract includes every response schema.

Authorizations

Authorization
string
header
required

The server's token (MIRAGE_AUTH_TOKEN) or a JWT. A daemon in the default local mode with no token accepts requests without one.

Path Parameters

workspace_id
string
required

Workspace ID.

Query Parameters

session_id
string

Session ID to use. If omitted, the default session is used.

explain
boolean
default:false

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.

stream
boolean
default:false

Return output as it is produced, as NDJSON records ending with a status record. Cannot be combined with explain.

Body

command
string
required

Shell command or script to execute.

cwd
string | null

Working directory for this command only. null is the same as omitting it.

machine
string | null

Name of an entry under machines in the workspace config. If omitted or null, the machine is selected automatically. A name the workspace does not have is refused with 400 before anything runs.

record
boolean | null
default:true

Include this command in session history. Set false to keep it out; null is the default.

open_stdin
boolean | null
default:false

Keep stdin open for additional input. Requires stream=true and no stdin part; the first response record contains line_id. null is the default.

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.

Returned by default, when the command has ended.

exit_code
integer
required

Exit status of the command. 0 is success and 127 command not found. 126 usually means a policy refused the command before it ran, but a refusal can leave another code; check decision.

stdout
string
required

Standard output, decoded as UTF-8. Empty in a stream's final record.

stderr
string
required

Standard error, decoded as UTF-8. Empty in a stream's final record.

decision
object | null
required

Set when a policy refused the command or any part of it, otherwise null. Part of the command may have run, and the exit code need not be 126.

line_id
string
required

Command execution ID. Use it with GET /v1/workspaces/{workspace_id}/lines/{line_id}.