Stream command output via WebSocket

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

string

required

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

Path parameters

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"]
}

Field	Type	Description
`type`	string	Must be `"start"`.
`cmd`	string	Command to execute.
`args`	string[]	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:

`type`	Fields	When sent
`start`	`pid: integer`	Process started; contains the OS PID.
`stdout`	`data: string`	A chunk of stdout arrived.
`stderr`	`data: string`	A chunk of stderr arrived.
`exit`	`exit_code: integer`	Process exited; connection closes automatically after this.
`error`	`data: string`	An 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

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

Stream command output via WebSocket

Endpoint

Authentication

Path parameters

WebSocket protocol

Client messages

Server messages

Python SDK

Errors

​Endpoint

​Authentication

​Path parameters

​WebSocket protocol

​Client messages

​Server messages

​Python SDK

​Errors

Endpoint

Authentication

Path parameters

WebSocket protocol

Client messages

Server messages

Python SDK

Errors