POST /v1/capsules/{id}/exec — Execute a command

Use this endpoint to run a command inside a running capsule. In foreground mode (the default), the request blocks until the process exits and returns the full stdout, stderr, and exit code. In background mode, the server starts the process and returns immediately with its PID and a tag you can use to stream or kill it later.

Endpoint

POST https://app.wrenn.dev/api/v1/capsules/{id}/exec

Authentication

string

required

Your team’s API key. Pass the full wrn_... key value.

Path parameters

string

required

The capsule ID.

Request body

string

required

The command to execute, e.g. "python" or "/bin/bash".

string[]

Arguments to pass to the command, e.g. ["-u", "train.py"].

integer

default:"30"

Maximum number of seconds to wait for the process to exit (foreground only). Set to 0 for no timeout.

object

Additional environment variables to inject into the process, e.g. {"DEBUG": "1"}. Background exec only.

string

Working directory for the process, e.g. "/workspace". Background exec only.

boolean

default:"false"

When true, the process is started in the background and the server responds immediately with HTTP 202. Use the returned pid or tag to stream or kill the process later.

Responses

200 — Foreground execution complete

Returned when background is false (or omitted). The process has exited and the full output is included.

string

Captured standard output. Base64-encoded when the output contains binary data (check the encoding field).

string

Captured standard error.

integer

Exit code returned by the process. 0 conventionally indicates success.

integer

Wall-clock time the process ran, in milliseconds.

string

Output encoding. Either "utf-8" or "base64". Check this field before decoding stdout/stderr.

202 — Background process started

Returned when background is true. The process is running inside the capsule; use the pid or tag with the processes endpoints to manage it.

integer

Operating system PID of the process inside the capsule.

string

Stable identifier for this background process. Auto-generated if you did not supply one in the request. Use this tag to stream or kill the process.

Examples

Foreground execution

Run a command and wait for the result:

curl -X POST https://app.wrenn.dev/api/v1/capsules/cap_abc123/exec \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "python",
    "args": ["-c", "print(\"hello\")"]
  }'

{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 83,
  "encoding": "utf-8"
}

Background execution

Start a long-running process without blocking:

curl -X POST https://app.wrenn.dev/api/v1/capsules/cap_abc123/exec \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "python",
    "args": ["-u", "server.py"],
    "background": true,
    "envs": {"PORT": "8080"},
    "cwd": "/workspace"
  }'

{
  "pid": 42,
  "tag": "bg-a1b2c3d4"
}

Python SDK

from wrenn import Capsule

with Capsule(wait=True) as capsule:
    # Foreground — blocks until done
    result = capsule.commands.run("python -c 'print(\"hello\")'")
    print(result.stdout)     # "hello\n"
    print(result.exit_code)  # 0

    # Background — returns immediately
    handle = capsule.commands.run("python -u server.py", background=True)
    print(handle.pid)  # e.g. 42
    print(handle.tag)  # e.g. "bg-a1b2c3d4"

Errors

Status	Meaning
`404`	Capsule not found or does not belong to your team.
`409`	Capsule is not in the `running` state. Start or resume the capsule first.

Capsules

Execution

Files

Snapshots

POST /v1/capsules/{id}/exec — Execute a command

Endpoint

Authentication

Path parameters

Request body

Responses

200 — Foreground execution complete

202 — Background process started

Examples

Foreground execution

Background execution

Python SDK

Errors

​Endpoint

​Authentication

​Path parameters

​Request body

​Responses

​200 — Foreground execution complete

​202 — Background process started

​Examples

​Foreground execution

​Background execution

​Python SDK

​Errors

Endpoint

Authentication

Path parameters

Request body

Responses

200 — Foreground execution complete

202 — Background process started

Examples

Foreground execution

Background execution

Python SDK

Errors