Skip to main content
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

​
X-API-Key
string
required
Your team’s API key. Pass the full wrn_... key value.

​
Path parameters

​
id
string
required
The capsule ID.

​
Request body

​
cmd
string
required
The command to execute, e.g. "python" or "/bin/bash".
​
args
string[]
Arguments to pass to the command, e.g. ["-u", "train.py"].
​
timeout
integer
default:"30"
Maximum number of seconds to wait for the process to exit (foreground only). Set to 0 for no timeout.
​
envs
object
Additional environment variables to inject into the process, e.g. {"DEBUG": "1"}. Background exec only.
​
cwd
string
Working directory for the process, e.g. "/workspace". Background exec only.
​
background
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.
​
stdout
string
Captured standard output. Base64-encoded when the output contains binary data (check the encoding field).
​
stderr
string
Captured standard error.
​
exit_code
integer
Exit code returned by the process. 0 conventionally indicates success.
​
duration_ms
integer
Wall-clock time the process ran, in milliseconds.
​
encoding
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.
​
pid
integer
Operating system PID of the process inside the capsule.
​
tag
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

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