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

​
X-API-Key
string
required
Your team’s API key.

​
Path parameters

​
id
string
required
The capsule ID.

​
Response (200)

​
processes
object[]
Array of process objects.
{
  "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

​
id
string
required
The capsule ID.
​
selector
string
required
A numeric PID (e.g. 42) or a string tag (e.g. bg-a1b2c3d4).

​
Query parameters

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

​
id
string
required
The capsule ID.
​
selector
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:
typeFieldsWhen sent
startpid: integerAttached to process.
stdoutdata: stringA chunk of stdout.
stderrdata: stringA chunk of stderr.
exitexit_code: integerProcess exited.
errordata: stringAn 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

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