Exec Contract

Exec is Quilt’s synchronous command surface.

Use it when you want a command to run inside a container and get the result back immediately, without opening an interactive terminal session.

Primary routes:

POST /api/containers/<container_id>/exec
POST /api/containers/<container_id>/stream

Exec Request

{
  "command": ["npm", "test"],
  "workdir": "/app",
  "timeout_ms": 30000
}

Important Semantics

• command must be a JSON array of strings
• exec blocks until the command exits and returns the result inline
• if shell parsing is required, invoke the shell explicitly
• the container must be running and minit must be healthy
• a non-zero exit_code is still returned as 200 OK if the command ran and failed
• timed_out: true means the command hit timeout_ms and was terminated
• /stream returns application/x-ndjson, one JSON frame per line
• stdout and stderr frames carry base64 bytes in data_b64

Choose the Right Surface

Need	Best route
Run a command and get the result inline	/exec
Watch output as it happens	/stream
Work interactively in a shell	terminal sessions

Response

POST /api/containers/:id/exec returns 200 OK with the completed result:

{
  "container_id": "ctr_123",
  "exit_code": 0,
  "stdout": "hello\n",
  "stderr": "",
  "execution_time_ms": 12,
  "timed_out": false
}

No job handle. No polling. The response body is the final result.

Live Stream Request

{
  "command": ["/bin/sh", "-lc", "echo hello && echo warn 1>&2"],
  "working_directory": "/app",
  "environment": {
    "NODE_ENV": "production"
  },
  "timeout_ms": 30000
}

Example Frames

{"type":"started","container_id":"ctr_123","pid":1234}
{"type":"stdout","data_b64":"aGVsbG8K"}
{"type":"stderr","data_b64":"d2Fybgo="}
{"type":"exit","code":0,"elapsed_ms":25}

Process Inspection Routes

GET    /api/containers/<container_id>/processes
DELETE /api/containers/<container_id>/processes/<pid>?signal=<signal>

Rule of Thumb

Use exec for automation and terminal sessions for human interaction. If you need shell features, make the shell invocation explicit in the command array.