Monitoring

Debugging

Inspect workloads, runners, and provider configuration on a Rivet control plane using the management and runner HTTP APIs.

Connecting to Rivet

All debugging endpoints in this guide are available both locally and in production. In local development, the base URL is http://localhost:6420 with no authentication. In production (Rivet Cloud or self-hosted), you connect to your Rivet control plane endpoint with a token.

Setup

All examples in this guide use these shell variables. Extract them from your RIVET_ENDPOINT (https://<namespace>:<token>@<host>):

# From RIVET_ENDPOINT=https://my-namespace:sk_abc123@api.rivet.dev
export RIVET_API="https://api.rivet.dev"
export RIVET_NAMESPACE="my-namespace"
export RIVET_TOKEN="sk_abc123"

# For local development:
# export RIVET_API="http://localhost:6420"

Rivet Cloud issues two token types: sk_ (secret key, server-side only) and pk_ (public key, client-safe). For debugging, always use sk_. See Endpoints for more details.

Management API

The management API runs on the manager base path (default root path) and is used to list, create, and look up actors.

Authentication

Environment	Authentication
Local development	No authentication required. All endpoints are accessible without tokens.
Self-hosted engine	Set `RIVET_TOKEN` to enable authenticated access to restricted endpoints like KV.
Rivet Cloud	Authentication is enforced by your deployment entrypoint. For manager KV access, use the bearer token header below when enabled.

Restricted endpoints (like KV reads) require the Authorization: Bearer header when RIVET_TOKEN is configured:

curl "$RIVET_API/actors/{actor_id}/kv/keys/{base64_key}" \
  -H "Authorization: Bearer $RIVET_TOKEN"

List Actors

# List all actors with a given name
curl "$RIVET_API/actors?name=my-actor&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

# Look up one actor by key (name is required when key is provided)
curl "$RIVET_API/actors?name=my-actor&key=%5B%22my-key%22%5D&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

# List actors by IDs (comma-separated)
curl "$RIVET_API/actors?actor_ids=id1,id2&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Rules:

key requires name.
actor_ids cannot be combined with name or key.

Returns:

{
  "actors": [
    {
      "actor_id": "abc123",
      "name": "my-actor",
      "key": "[\"default\"]",
      "namespace_id": "default",
      "create_ts": 1706000000000
    }
  ]
}

Create Actor

POST /actors creates a new actor.

curl -X POST "$RIVET_API/actors?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-actor",
    "runner_name_selector": "default",
    "crash_policy": "restart"
  }'

Create or Get Actor

PUT /actors creates an actor if it does not exist, otherwise returns the existing one.

curl -X PUT "$RIVET_API/actors?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-actor",
    "key": "[\"default\"]",
    "runner_name_selector": "default",
    "crash_policy": "restart"
  }'

Returns the actor object with its actor_id.

List Actor Names

curl "$RIVET_API/actors/names?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Returns all registered actor names and their metadata.

Read Actor KV

Requires authentication (see above).

curl "$RIVET_API/actors/{actor_id}/kv/keys/{base64_key}" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Returns the value stored at the given key in the actor KV compatibility snapshot. After an actor has migrated to SQLite-backed runtime storage, this endpoint is stale for user KV and internal runtime records; it continues to expose the frozen pre-migration KV data. The inspector token key is the exception and remains mirrored for dashboard compatibility.

See the OpenAPI spec for the full schema of all management endpoints.

Runner API

Use the runner endpoints to debug scheduler capacity and provider configuration (for example serverless URL, headers, and limits) through the Rivet API.

List Runner Names

curl "$RIVET_API/runners/names?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Returns the runner pools available in the namespace:

{
  "names": ["default", "gpu-workers"],
  "pagination": { "cursor": null }
}

List Runners in a Pool

curl "$RIVET_API/runners?namespace=$RIVET_NAMESPACE&name=default&include_stopped=true&limit=100" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Useful fields when debugging:

remaining_slots / total_slots for capacity.
drain_ts and stop_ts for shutdown behavior.
last_ping_ts and last_connected_ts for connectivity.

Inspect Provider Config (Runner Config)

curl "$RIVET_API/runner-configs?namespace=$RIVET_NAMESPACE&runner_name=default" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Returns the configured provider settings per datacenter and the latest pool error (if any):

{
  "runner_configs": {
    "default": {
      "datacenters": {
        "dc-1": {
          "serverless": {
            "url": "https://your-deployment.example.com/rivet",
            "headers": { "Authorization": "Bearer token" },
            "request_lifespan": 55,
            "slots_per_runner": 1,
            "max_runners": 10
          },
          "runner_pool_error": null
        }
      }
    }
  },
  "pagination": { "cursor": null }
}

runner_pool_error mirrors actor scheduling errors such as serverless_http_error, serverless_connection_error, serverless_destination_blocked, and serverless_stream_ended_early.

Check Serverless Provider Health

Use this to test whether Rivet can reach your serverless provider URL and read runner metadata:

curl -X POST "$RIVET_API/runner-configs/serverless-health-check?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-deployment.example.com/rivet",
    "headers": {
      "Authorization": "Bearer token"
    }
  }'

Possible responses:

{ "success": { "version": "1.2.3" } }

{
  "failure": {
    "error": {
      "message": "non-success status from metadata endpoint",
      "details": "received status 503"
    }
  }
}

Refresh Provider Metadata

If you deploy new actor code or routes and metadata has not updated yet, force a refresh:

curl -X POST "$RIVET_API/runner-configs/default/refresh-metadata?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

OpenAPI Spec

An OpenAPI specification covering many of the management and actor endpoints is available:

In the repository at rivetkit-openapi/openapi.json
Served at /doc on the manager when running locally

The checked-in spec does not yet list every endpoint documented here and in Debugging Actors (for example the actor metadata and queue routes and the inspector database routes), so treat those pages as the authoritative reference where they differ.