Deploying to Rivet Compute

Steps

• Your RivetKit app
  • If you don't have one, see the Quickstart page or our Examples
• A Rivet Cloud account and project
• Docker running locally

Add a Dockerfile to your project root that builds and runs your RivetKit server:

FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
CMD ["node", "src/server.js"]

1. Open the Rivet dashboard and navigate to your project
2. Click Connect and select Rivet Cloud
3. Copy the RIVET_CLOUD_TOKEN value shown

Run the deploy command from your project root. The token is saved to ~/.rivet/credentials, so later deploys can omit it.

npx @rivetkit/cli deploy --token cloud_api_xxxxx

The CLI resolves your project from the token, builds and pushes your Docker image to Rivet's built-in registry, upserts the managed pool, and prints the deployment URL on stdout when the pool is ready.

After local deploys work, install the GitHub Actions workflow that deploys on every push and pull request:

npx @rivetkit/cli setup-ci

This writes .github/workflows/rivet-deploy.yml. Add your token as a repository secret to enable it:

gh secret set RIVET_CLOUD_TOKEN

The workflow creates production and pull-request namespaces, posts preview links, and cleans up PR namespaces when pull requests close. See the CLI reference for all commands.

The dashboard shows live status as Rivet Compute provisions your backend:

Once the status reaches Ready, your backend is live and actors are available for connections.

If you are an agent monitoring the deployment via API rather than the dashboard, poll the managed-pool endpoint on the Cloud API.

The RIVET_CLOUD_TOKEN secret is a cloud_api_* management token scoped to the Cloud API at cloud-api.rivet.dev. Use it for Authorization: Bearer ... against the Cloud API. Do not confuse it with a pk_* publishable key, which is scoped to the Rivet Engine API at api.rivet.dev and will 401 against this endpoint.

Substitute $CLOUD_API_URL (typically https://cloud-api.rivet.dev), $PROJECT, $ORG, $CLOUD_NAMESPACE, and $CLOUD_TOKEN.

Poll every 5 seconds until status is ready. Stop and investigate if status is error.

curl -s "$CLOUD_API_URL/projects/$PROJECT/namespaces/$CLOUD_NAMESPACE/managed-pools/default?org=$ORG" -H "Authorization: Bearer $CLOUD_TOKEN"

Checking Logs

Use the CLI to read your deployment's logs. By default rivet logs prints the last 100 lines from the production namespace, oldest to newest, then exits.

npx @rivetkit/cli logs

The CLI resolves your token the same way deploy does (the --token flag, then the RIVET_CLOUD_TOKEN environment variable, then ~/.rivet/credentials).

Follow logs live

Pass --follow (-f) to stream new logs as they arrive instead of fetching history:

npx @rivetkit/cli logs --follow

Each formatted line is printed as <timestamp> [<SEVERITY>] <region> <message>:

2026-06-16T18:26:51.160Z [INFO] eu-central-1 server listening on port 3000
2026-06-17T11:24:20.425Z [ERROR] us-east-1 failed to connect to upstream

A few examples:

# Last 200 lines from a specific namespace
npx @rivetkit/cli logs --namespace production -n 200

# Live tail, only lines containing "error"
npx @rivetkit/cli logs --follow --contains error

# JSON output piped to jq
npx @rivetkit/cli logs -n 50 --json | jq .

Troubleshooting

If the status stays in Initializing for more than a few minutes, verify that:

• The RIVET_CLOUD_TOKEN secret is correctly set in your GitHub repository
• The GitHub Actions workflow completed without errors — check the run logs

If the status shows Error, check that your container starts successfully and does not exit immediately (you can check this with container logs). Common causes:

• The server file is not calling registry.start()
• A runtime crash on startup — test the image locally with docker run
• The server is not listening on the RIVET_PORT environment variable (RivetKit reads RIVET_PORT, defaulting to 3000)

Pricing

You are billed for the compute resources your deployment uses while it is running.