Skip to main content
Sign In
More

Debugging

Inspect and debug running Rivet Actors, runners, and provider configs using management, runner, and actor inspector HTTP APIs.

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

EnvironmentAuthentication
Local developmentNo authentication required. All endpoints are accessible without tokens.
Self-hosted engineSet RIVET_TOKEN to enable authenticated access to restricted endpoints like KV.
Rivet CloudAuthentication is enforced by your deployment entrypoint. For manager KV access, use the manager token header below when enabled.

Restricted endpoints (like KV reads) require the x-rivet-token header when RIVET_TOKEN is configured:

curl http://localhost:6420/actors/{actor_id}/kv/keys/{base64_key} \
  -H 'x-rivet-token: YOUR_RIVET_TOKEN'

List Actors

# List all actors with a given name
curl http://localhost:6420/actors?name=my-actor

# Look up one actor by key (name is required when key is provided)
curl "http://localhost:6420/actors?name=my-actor&key=%5B%22my-key%22%5D"

# List actors by IDs (comma-separated)
curl http://localhost:6420/actors?actor_ids=id1,id2

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 http://localhost:6420/actors \
  -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 http://localhost:6420/actors \
  -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 http://localhost:6420/actors/names?namespace=default

Returns all registered actor names and their metadata.

Read Actor KV

Requires authentication (see above).

curl http://localhost:6420/actors/{actor_id}/kv/keys/{base64_key} \
  -H 'x-rivet-token: YOUR_RIVET_TOKEN'

Returns the value stored at the given key.

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.

Base URL and Auth

Use your local manager URL in development (http://localhost:6420) or https://api.rivet.dev when using Rivet API.

If auth is enabled, pass a bearer token:

export RIVET_API="https://api.rivet.dev"
export RIVET_NAMESPACE="default"
export RIVET_TOKEN="YOUR_ADMIN_TOKEN"

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, 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 '{}'

Actor API

All actor-level endpoints are accessed through the gateway. The gateway routes requests to the correct actor instance using the actor ID in the URL path:

http://localhost:6420/gateway/{actor_id}/{path}

The gateway only accepts actor IDs, not names. Use GET /actors?name=... from the management API to look up actor IDs first.

Authentication

Standard actor endpoints (health, actions, requests) and inspector endpoints have separate authentication requirements.

Standard Endpoints

EnvironmentAuthentication
Local developmentNo authentication required.
Self-hosted engineThe Rivet Engine handles authentication at the gateway level.
Rivet CloudAuthentication is handled by the Rivet Cloud platform at the gateway level.

Inspector Endpoints

EnvironmentAuthentication
Local developmentNo authentication required if RIVET_INSPECTOR_TOKEN is not set. A warning is logged.
Self-hosted engineSet the RIVET_INSPECTOR_TOKEN environment variable. Pass it as a bearer token in the Authorization header.
Rivet CloudToken is required. Pass it as a bearer token in the Authorization header.
curl http://localhost:6420/gateway/{actor_id}/inspector/summary \
  -H 'Authorization: Bearer YOUR_INSPECTOR_TOKEN'

Standard Actor Endpoints

These are the built-in actor endpoints available through the gateway:

# Health check
curl http://localhost:6420/gateway/{actor_id}/health

# Metadata
curl http://localhost:6420/gateway/{actor_id}/metadata

# Call an action
curl -X POST http://localhost:6420/gateway/{actor_id}/action/myAction \
  -H 'Content-Type: application/json' \
  -d '{"args": [1, 2, 3]}'

# Send queue message (body includes queue name)
curl -X POST http://localhost:6420/gateway/{actor_id}/queue \
  -H 'Content-Type: application/json' \
  -d '{"name":"jobs","body":{"id":"job-1"}}'

# Send queue message (queue name in path)
curl -X POST http://localhost:6420/gateway/{actor_id}/queue/jobs \
  -H 'Content-Type: application/json' \
  -d '{"body":{"id":"job-1"}}'

# Send queue message and wait for completion (optional timeout in ms)
curl -X POST http://localhost:6420/gateway/{actor_id}/queue/jobs \
  -H 'Content-Type: application/json' \
  -d '{"body":{"id":"job-1"},"wait":true,"timeout":5000}'

# Forward an HTTP request to the actor's onRequest handler
curl http://localhost:6420/gateway/{actor_id}/request/my/custom/path

Queue send responses include:

{ "status": "completed", "response": null }

If wait: true and the timeout is reached, status is "timedOut".

Inspector Endpoints

The inspector HTTP API exposes JSON endpoints for querying and modifying actor internals at runtime. These are designed for agent-based debugging and tooling.

Get State

curl http://localhost:6420/gateway/{actor_id}/inspector/state

Returns the actor’s current persisted state:

{
  "state": { "count": 42, "users": [] },
  "isStateEnabled": true
}

Set State

curl -X PATCH http://localhost:6420/gateway/{actor_id}/inspector/state \
  -H 'Content-Type: application/json' \
  -d '{"state": {"count": 0, "users": []}}'

Returns:

{ "ok": true }

Get Connections

curl http://localhost:6420/gateway/{actor_id}/inspector/connections

Returns all active connections with their params, state, and metadata:

{
  "connections": [
    {
      "type": "websocket",
      "id": "conn-id",
      "details": {
        "type": "websocket",
        "params": {},
        "stateEnabled": true,
        "state": {},
        "subscriptions": 2,
        "isHibernatable": true
      }
    }
  ]
}

Get RPCs

curl http://localhost:6420/gateway/{actor_id}/inspector/rpcs

Returns a list of available actions:

{ "rpcs": ["increment", "getCount"] }

Execute Action

curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/action/increment \
  -H 'Content-Type: application/json' \
  -d '{"args": [5]}'

Returns:

{ "output": 47 }

Get Queue Status

curl http://localhost:6420/gateway/{actor_id}/inspector/queue?limit=10

Returns queue status with messages:

{
  "size": 3,
  "maxSize": 1000,
  "truncated": false,
  "messages": [
    { "id": 1, "name": "process", "createdAtMs": 1706000000000 }
  ]
}

Get Traces

Query trace spans in OTLP JSON format:

curl "http://localhost:6420/gateway/{actor_id}/inspector/traces?startMs=0&endMs=9999999999999&limit=100"

Returns:

{
  "otlp": {
    "resourceSpans": [
      {
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "abc123",
                "spanId": "def456",
                "name": "increment",
                "startTimeUnixNano": "1706000000000000000"
              }
            ]
          }
        ]
      }
    ]
  },
  "clamped": false
}

Get Workflow History

curl http://localhost:6420/gateway/{actor_id}/inspector/workflow-history

Returns:

{
  "history": null,
  "isWorkflowEnabled": false
}

Summary

Get a full snapshot of the actor in a single request:

curl http://localhost:6420/gateway/{actor_id}/inspector/summary

Returns:

{
  "state": { "count": 42 },
  "connections": [],
  "rpcs": ["increment", "getCount"],
  "queueSize": 0,
  "isStateEnabled": true,
  "isDatabaseEnabled": false,
  "isWorkflowEnabled": false,
  "workflowHistory": null
}

Polling

Inspector endpoints are safe to poll. For live monitoring, poll at 1-5 second intervals. The /inspector/summary endpoint is useful for periodic snapshots since it returns all data in a single request.

OpenAPI Spec

The full OpenAPI specification including all management and actor endpoints is available:

Edit this page