Manage Running Processes in a Wrenn Capsule

Background processes — started with background: true on the exec endpoint — continue running inside the capsule until they exit or you stop them. The processes endpoints let you inspect what is running, send signals to terminate processes, and attach a streaming WebSocket to a process that is already underway.

List processes

GET https://app.wrenn.dev/api/v1/capsules/{id}/processes

Returns all processes currently running inside the capsule, including background processes started via the API and any processes launched by the capsule’s init scripts or template.

Authentication

string

required

Your team’s API key.

Path parameters

string

required

The capsule ID.

Response (200)

object[]

Array of process objects.

Show process fields

integer

Operating system PID of the process inside the capsule.

string

Stable tag for this process. Auto-generated when the process was started via the API; empty for init/template processes.

string

The command used to start the process.

string[]

Arguments the process was started with.

{
  "processes": [
    {
      "pid": 42,
      "tag": "bg-a1b2c3d4",
      "cmd": "python",
      "args": ["-u", "server.py"]
    },
    {
      "pid": 7,
      "tag": "",
      "cmd": "/usr/sbin/sshd",
      "args": ["-D"]
    }
  ]
}

Python SDK

with Capsule(wait=True) as capsule:
    procs = capsule.commands.list()
    for p in procs:
        print(p.pid, p.tag, p.cmd)

Kill a process

DELETE https://app.wrenn.dev/api/v1/capsules/{id}/processes/{selector}

Sends a signal to a running process. You can identify the process by its numeric PID or by its string tag.

Path parameters

string

required

The capsule ID.

string

required

A numeric PID (e.g. 42) or a string tag (e.g. bg-a1b2c3d4).

Query parameters

string

default:"SIGKILL"

Signal to send to the process. Accepted values: SIGKILL (immediate termination) or SIGTERM (graceful shutdown request).

Response

Returns HTTP 204 with no body on success.

Examples

Kill by PID with the default signal (SIGKILL):

curl -X DELETE \
  "https://app.wrenn.dev/api/v1/capsules/cap_abc123/processes/42" \
  -H "X-API-Key: wrn_your_api_key_here"

Kill by tag with SIGTERM:

curl -X DELETE \
  "https://app.wrenn.dev/api/v1/capsules/cap_abc123/processes/bg-a1b2c3d4?signal=SIGTERM" \
  -H "X-API-Key: wrn_your_api_key_here"

Python SDK

kill() accepts a PID. To send SIGTERM instead of the default SIGKILL, use the REST API directly with the ?signal=SIGTERM query parameter — the SDK always sends SIGKILL.

with Capsule(wait=True) as capsule:
    capsule.commands.kill(pid=1234)

Stream a running process

GET https://app.wrenn.dev/api/v1/capsules/{id}/processes/{selector}/stream

Opens a WebSocket connection to attach to a background process that is already running. You receive stdout and stderr from the point of connection onwards, plus an exit message when the process terminates.

This endpoint attaches to an existing process. To start a new process and stream it from the beginning, use the exec/stream endpoint instead.

Path parameters

string

required

The capsule ID.

string

required

A numeric PID or string tag identifying the process to attach to.

Server messages

Once connected, the server streams the same message format as the exec/stream endpoint:

`type`	Fields	When sent
`start`	`pid: integer`	Attached to process.
`stdout`	`data: string`	A chunk of stdout.
`stderr`	`data: string`	A chunk of stderr.
`exit`	`exit_code: integer`	Process exited.
`error`	`data: string`	An error occurred.

Python SDK

with Capsule(wait=True) as capsule:
    handle = capsule.commands.run("python", args=["-u", "server.py"], background=True)

    # Later — attach to the running process
    for event in capsule.commands.connect(handle.pid):
        if event.type == "stdout":
            print(event.data, end="")
        elif event.type == "exit":
            print(f"Exited: {event.exit_code}")

Errors

Status	Meaning
`404`	Capsule not found, or the process identified by the selector does not exist.
`409`	Capsule is not in the `running` state.

Capsules

Execution

Files

Snapshots

Manage Running Processes in a Wrenn Capsule

List processes

Authentication

Path parameters

Response (200)

Python SDK

Kill a process

Path parameters

Query parameters

Response

Examples

Python SDK

Stream a running process

Path parameters

Server messages

Python SDK

Errors

​List processes

​Authentication

​Path parameters

​Response (200)

​Python SDK

​Kill a process

​Path parameters

​Query parameters

​Response

​Examples

​Python SDK

​Stream a running process

​Path parameters

​Server messages

​Python SDK

​Errors

List processes

Authentication

Path parameters

Response (200)

Python SDK

Kill a process

Path parameters

Query parameters

Response

Examples

Python SDK

Stream a running process

Path parameters

Server messages

Python SDK

Errors