Skip to main content
This endpoint upgrades an HTTP connection to a WebSocket so you can stream command output as it is produced. Unlike the blocking exec endpoint, output arrives event by event — useful for long-running processes, build jobs, or any command where you want to display progress in real time.

​
Endpoint

GET https://app.wrenn.dev/api/v1/capsules/{id}/exec/stream
Upgrade this request to a WebSocket by including the standard Upgrade: websocket headers.

​
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.

​
WebSocket protocol

Once the connection upgrades (HTTP 101), you control the session with JSON messages.

​
Client messages

Start a process — send this as the first message after connecting: 
{
  "type": "start",
  "cmd": "tail",
  "args": ["-f", "/var/log/app.log"]
}
FieldTypeDescription
typestringMust be "start".
cmdstringCommand to execute.
argsstring[]Arguments to pass to the command.
Stop the process — send this to terminate the running process early: 
{
  "type": "stop"
}

​
Server messages

The server emits JSON messages as the process produces output:
typeFieldsWhen sent
startpid: integerProcess started; contains the OS PID.
stdoutdata: stringA chunk of stdout arrived.
stderrdata: stringA chunk of stderr arrived.
exitexit_code: integerProcess exited; connection closes automatically after this.
errordata: stringAn error occurred (e.g. command not found).
{"type": "start", "pid": 1234}
{"type": "stdout", "data": "step 1 complete\n"}
{"type": "stderr", "data": "warning: deprecated flag\n"}
{"type": "exit", "exit_code": 0}
The connection closes automatically once the server sends an exit message. You do not need to close it manually.

​
Python SDK

The SDK wraps the WebSocket protocol and yields events as an iterator: 
from wrenn import Capsule

with Capsule(wait=True) as capsule:
    for event in capsule.commands.stream("python", args=["-u", "train.py"]):
        if event.type == "stdout":
            print(event.data, end="")
        elif event.type == "stderr":
            print("[err]", event.data, end="")
        elif event.type == "exit":
            print(f"\nExited with code {event.exit_code}")

​
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.