puter/zopu-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add AgentOS daemon control plane and maintenance tooling

Browse Source
This commit is contained in:
-Puter
2026-07-19 06:29:51 +05:30
parent a37e0cc3c9
commit ec84c52155
621 changed files with 97578 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
.agents/skills/rivetkit/reference/deploy/aws-ecs.md Normal file
View File

@@ -0,0 +1,13 @@
# Deploying to AWS ECS
> Source: `src/content/docs/deploy/aws-ecs.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/aws-ecs
> Description: Run your backend on Amazon ECS with Fargate.
---
See the [AWS ECS template](https://github.com/rivet-dev/template-aws-ecs) for deployment instructions:
- [Deploy with Terraform](https://github.com/rivet-dev/template-aws-ecs#option-a-deploy-with-terraform)
- [Deploy with AWS CLI](https://github.com/rivet-dev/template-aws-ecs#option-b-deploy-with-aws-cli)
_Source doc path: /docs/deploy/aws-ecs_

10
.agents/skills/rivetkit/reference/deploy/aws-lambda.md Normal file
View File

@@ -0,0 +1,10 @@
# Deploy To Amazon Web Services Lambda
> Source: `src/content/docs/deploy/aws-lambda.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/aws-lambda
> Description: _AWS Lambda is coming soon_
---
_Source doc path: /docs/deploy/aws-lambda_

53
.agents/skills/rivetkit/reference/deploy/cloudflare.md Normal file
View File

@@ -0,0 +1,53 @@
# Deploying to Cloudflare Workers
> Source: `src/content/docs/deploy/cloudflare.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/cloudflare
> Description: Deploy an existing Rivet project to Cloudflare Workers.
---
This guide covers deploying an existing Rivet project to Cloudflare Workers.
## Prerequisites
- [Cloudflare account](https://dash.cloudflare.com/)
- [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) configured for your account
- A Rivet namespace from the [Rivet Dashboard](https://dashboard.rivet.dev/) or a self-hosted Rivet Engine
## Steps
### Set up your project
Follow the [Cloudflare Workers Quickstart](/docs/actors/quickstart/cloudflare) to set up your project locally.
### Configure Wrangler
Set your Rivet connection values as Worker variables. Find `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` in the [Rivet Dashboard](https://dashboard.rivet.dev/) under **Settings → Namespace → Advanced → Backend Configuration** and copy them in.
```toml wrangler.toml
name = "rivetkit-cloudflare"
main = "src/index.ts"
compatibility_date = "2025-04-01"
compatibility_flags = ["nodejs_compat"]
[vars]
RIVET_ENDPOINT = "https://your-namespace:sk_...@api.rivet.dev"
RIVET_PUBLIC_ENDPOINT = "https://your-namespace@api.rivet.dev"
```
### Deploy
```sh
npx wrangler deploy
```
### Register the Serverless Runner URL
After deploy, set the Worker URL with the `/api/rivet` path as the serverless runner URL in Rivet.
## Related
- [Cloudflare Workers Quickstart](/docs/actors/quickstart/cloudflare)
- [Deploying to Supabase Functions](/docs/deploy/supabase)
- [SQLite](/docs/actors/sqlite)
_Source doc path: /docs/deploy/cloudflare_

95
.agents/skills/rivetkit/reference/deploy/container-runner.md Normal file
View File

@@ -0,0 +1,95 @@
# Container Runner
> Source: `src/content/docs/deploy/container-runner.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/container-runner
> Description: Run any containerized server as a Rivet Actor.
---
The container runner (`rivet-container-runner`) is an adapter for running arbitrary containers as Rivet Actors. Use it for non-RivetKit workloads such as Unity or Godot dedicated game servers and batch jobs like FFmpeg transcoding.
## Steps
### Prerequisites
- A containerized server (a Unity or Godot dedicated server, a plain Node process, or any HTTP/WebSocket server)
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
- Docker running locally
### Install in Your Container
Download the static binary from Rivet's release artifacts in your Dockerfile and set it as the entrypoint, passing your server's launch command after `--`:
```dockerfile @nocheck
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl && rm -rf /var/lib/apt/lists/*
# Install the Rivet container runner.
RUN curl -fsSL https://releases.rivet.dev/rivet/latest/container-runner/rivet-container-runner-x86_64-unknown-linux-musl \
-o /usr/local/bin/rivet-container-runner \
&& chmod +x /usr/local/bin/rivet-container-runner
# Your server binary and assets.
COPY build/ /game/
WORKDIR /game
ENTRYPOINT ["rivet-container-runner", "--", "./GameServer", "-batchmode", "-nographics", "-logFile", "-"]
```
Artifacts are published for `x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl`. The binaries are fully static, so they run in any Linux base image, including `scratch`. Pin a version by replacing `latest` with a release version, for example `https://releases.rivet.dev/rivet/2.3.3/container-runner/rivet-container-runner-x86_64-unknown-linux-musl`.
### Deploy
Deploy the image to [Rivet Compute](/docs/deploy/rivet-compute) with the CLI. For game servers, configure the pool with one actor per instance:
```bash
npx @rivetkit/cli deploy \
--token "$RIVET_CLOUD_TOKEN" \
--instance-request-concurrency 1 \
--dockerfile Dockerfile
```
### Create Actors and Connect Clients
Create actors against the pool's runner (`default`) and connect clients through the gateway URL shown in the dashboard. WebSocket clients connect at the bare gateway URL with the `rivet` WebSocket subprotocol.
## How It Works
1. The engine cold-starts your container and calls `POST /api/rivet/start` on the port it injects as `RIVET_PORT`.
2. The runner spawns your server as a child process with `PORT` set to the child port, waits for the port to open, and reports the actor as running.
3. Gateway traffic for the actor arrives over Rivet's tunnel and is proxied to `127.0.0.1:<child port>`. WebSocket clients connect at the bare gateway URL with the `rivet` WebSocket subprotocol. Raw HTTP reaches the child under the `/request/*` prefix on the actor surface (the prefix is stripped before proxying); other paths are reserved for the runtime's own endpoints.
4. Child stdout and stderr are re-emitted with an `[actorId=... key=...]` prefix so actor logs are attributed in the dashboard.
5. When an actor stops, the runner sends its child `SIGTERM`, escalates to `SIGKILL` after a grace period, and exits the process once no actors remain.
## Configuration
All flags can also be set through environment variables:
| Flag | Environment variable | Default | Description |
| --- | --- | --- | --- |
| `--port` | `RIVET_PORT` / `PORT` | `8080` | Serverless front-door HTTP port. Rivet Compute injects `RIVET_PORT` automatically. |
| `--child-port` | `CHILD_PORT` | `7770` | First local child port; each actor's child gets the next free port at or above this, exported to the child as `PORT`. |
| `--actor-name` | `RIVET_ACTOR_NAME` | `game` | Actor name this runner serves. |
| `--runner-version` | `RIVET_RUNNER_VERSION` | `1` | Version reported to the engine, used to drain old runners on deploy. |
| `--base-path` | `RIVET_SERVERLESS_BASE_PATH` | `/api/rivet` | Base path the engine calls for serverless start. |
| `--stop-grace-secs` | `RIVET_STOP_GRACE_SECS` | `25` | `SIGTERM` to `SIGKILL` grace period when stopping the child. Capped to a few seconds when the platform itself is reclaiming the instance, so shutdown fits inside the platform's own kill window. |
| `--readiness-timeout-secs` | `RIVET_READINESS_TIMEOUT_SECS` | `30` | How long to wait for the child's port to open before failing the start. |
### Per-Actor Input
The actor's `input` payload can override the launch spec per actor. All fields are optional and fall back to the entrypoint command. RivetKit clients pass this object directly; when creating actors through the raw engine API, encode it as CBOR before base64-encoding the `input` field:
```json
{
"command": ["./GameServer", "-batchmode"],
"args": ["-extra-flag"],
"env": { "MATCH_MODE": "ranked" }
}
```
`command` replaces the entrypoint command template, `args` are appended to it, and `env` adds environment variables for the child.
## Source and Examples
The runner and a full end-to-end example, including a Unity FishNet demo project and a local test harness, live in the Rivet repository under [`container-runner/`](https://github.com/rivet-dev/rivet/tree/main/container-runner).
_Source doc path: /docs/deploy/container-runner_

136
.agents/skills/rivetkit/reference/deploy/freestyle.md Normal file
View File

@@ -0,0 +1,136 @@
# Deploying to Freestyle
> Source: `src/content/docs/deploy/freestyle.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/freestyle
> Description: Deploy RivetKit app to Freestyle.sh, a cloud platform for running AI-generated code with built-in security and scalability.
---
Freestyle provides built-in security for running untrusted AI-generated code, making it ideal for AI agent applications. Using Rivet, it is easy to deploy your vibe-coded or user-provided RivetKit backends straight to Freestyle.
- [Freestyle + Rivet](https://github.com/rivet-dev/rivet/tree/main/examples/freestyle) — Complete example of deploying RivetKit app to Freestyle.sh.
## Setup
### Install packages
Install RivetKit and Hono and create your registry:
```bash
npm install rivetkit hono
```
### Configure serverless driver
Update your server code to run the registry serverless with Deno.
```typescript index.ts @hide
import { actor, setup } from "rivetkit";
export const counter = actor({
state: { count: 0 },
actions: {
increment: (c, x: number) => {
c.state.count += x;
return c.state.count;
},
},
});
export const registry = setup({
use: { counter },
});
registry.start();
```
```typescript server.ts @nocheck
import { registry } from "./index";
// Freestyle uses Deno under the hood for web deployments
// @ts-ignore Deno is a Freestyle runtime global
Deno.serve((request: Request) => registry.handler(request));
```
The `Deno.serve` API is provided by Freestyle's runtime environment. The `@ts-ignore` comment suppresses TypeScript errors for this platform-specific API.
### Deploy to Freestyle
Deploy your application to Freestyle with the correct configuration. Create a deployment script or add this to your existing deployment process:
```typescript @nocheck
const FREESTYLE_DOMAIN = "my-domain.style.dev"; // Change to your desired Freestyle domain
declare const freestyle: any;
declare const buildDir: string;
const res = await freestyle.deployWeb(buildDir, {
envVars: {
FREESTYLE_ENDPOINT: `https://${FREESTYLE_DOMAIN}`,
RIVET_RUNNER_KIND: "serverless",
// For self-hosted instances:
// RIVET_ENDPOINT: "http://127.0.0.1:6420",
RIVET_ENDPOINT: "api.rivet.dev",
},
timeout: 60 * 5, // Increases max request lifetime on the runner
entrypoint: "server.ts", // File which starts serverless runner
domains: [FREESTYLE_DOMAIN],
build: false,
});
```
Details on `buildDir` and other settings are available on [Freestyle docs](https://docs.freestyle.sh/web/web).
Run this deployment script to push your application to Freestyle.
**Deployment Configuration:**
- `timeout: 60 * 5` - Set timeout to 5 minutes for actor operations - it's important to keep this high
- `entrypoint: "server.ts"` - Entry point file with your serverless setup
- `domains` - Your Freestyle domain(s)
- `build: false` - Disable build if you're pre-building your assets
### Configure runner
Update the runner configuration on the Rivet side to connect with your Freestyle deployment. Create a configuration script and run it after your Freestyle deployment is live:
```typescript @nocheck
import { RivetClient } from "@rivetkit/engine-api-full";
const rivet = new RivetClient({
environment: "https://api.rivet.dev",
token: process.env.RIVET_API_TOKEN,
});
const FREESTYLE_DOMAIN = "my-domain.style.dev"; // Change to your desired Freestyle domain
const RIVET_NAMESPACE = "my-rivet-namespace"; // Change to your Rivet namespace
await rivet.runnerConfigsUpsert("freestyle-runner", {
namespace: RIVET_NAMESPACE,
datacenters: {
default: {
serverless: {
url: `https://${FREESTYLE_DOMAIN}/start`,
runnersMargin: 1,
minRunners: 1,
maxRunners: 1,
slotsPerRunner: 1,
// Must be shorter than Freestyle request `timeout` config
requestLifespan: 60 * 5 - 5,
},
},
},
});
```
Execute this configuration script to register your Freestyle deployment with Rivet.
**Runner Configuration:**
- `url` - Freestyle deployment URL with `/start` endpoint
- `runnersMargin` - Buffer of runners to maintain
- `minRunners/maxRunners` - Scaling limits
- `slotsPerRunner` - Concurrent actors per runner
- `requestLifespan` - Request timeout (slightly less than Freestyle timeout)
Once executed, Rivet will be connected to your Freestyle serverless instance.
_Source doc path: /docs/deploy/freestyle_

74
.agents/skills/rivetkit/reference/deploy/gcp-cloud-run.md Normal file
View File

@@ -0,0 +1,74 @@
# Deploying to Google Cloud Run
> Source: `src/content/docs/deploy/gcp-cloud-run.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/gcp-cloud-run
> Description: Deploy your RivetKit app to Google Cloud Run.
---
## Steps
### Prerequisites
- Google Cloud project with Cloud Run and Artifact Registry enabled
- `gcloud` CLI authenticated (`gcloud auth login`) and project set (`gcloud config set project YOUR_PROJECT`)
- Artifact Registry repository or Container Registry enabled
- Your RivetKit app
- If you don't have one, see the [Quickstart](/docs/actors/quickstart) page or our [Examples](https://github.com/rivet-dev/rivet/tree/main/examples)
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
### Package Your App
Create a `Dockerfile` in your project root:
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV PORT=8080
CMD ["node", "server.js"]
```
### Build and Push the Image
Use Cloud Build to build and push the image. Replace the region and repository with your own.
```bash
gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT/rivetkit-app/rivetkit-app:latest
```
### Set Environment Variables
After creating your project on the Rivet dashboard, select Google Cloud Run as your provider. You'll be provided `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` environment variables to use when deploying.
### Deploy to Cloud Run
Deploy the service to Cloud Run, passing the Rivet environment variables. Adjust the region and image as needed.
```bash
gcloud run deploy rivetkit-app \
--image us-central1-docker.pkg.dev/YOUR_PROJECT/rivetkit-app/rivetkit-app:latest \
--region us-central1 \
--allow-unauthenticated \
--min-instances 1 \
--set-env-vars RIVET_ENDPOINT=<your-rivet-endpoint>,RIVET_PUBLIC_ENDPOINT=<your-rivet-public-endpoint>
```
### Connect to Rivet
1. After deployment, note the service URL (e.g. `https://rivetkit-app-xxxxx-uc.a.run.app`)
2. On the Rivet dashboard, paste your URL with the `/api/rivet` path into the connect form (e.g. `https://rivetkit-app-xxxxx-uc.a.run.app/api/rivet`)
3. Click "Done"
### Verify
Confirm the service is running:
```bash
gcloud run services describe rivetkit-app --region us-central1 --format 'value(status.conditions[?type="Ready"].status)'
```
Your app should appear as connected on the Rivet dashboard once the service reports ready.
_Source doc path: /docs/deploy/gcp-cloud-run_

10
.agents/skills/rivetkit/reference/deploy/hetzner.md Normal file
View File

@@ -0,0 +1,10 @@
# Deploying to Hetzner
> Source: `src/content/docs/deploy/hetzner.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/hetzner
> Description: Please see the VM & Bare Metal guide.
---
_Source doc path: /docs/deploy/hetzner_

121
.agents/skills/rivetkit/reference/deploy/kubernetes.md Normal file
View File

@@ -0,0 +1,121 @@
# Deploying to Kubernetes
> Source: `src/content/docs/deploy/kubernetes.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/kubernetes
> Description: Deploy your RivetKit app to any Kubernetes cluster.
---
## Steps
### Prerequisites
- A Kubernetes cluster with `kubectl` access (EKS, GKE, k3s, etc.)
- Container registry credentials (Docker Hub, GHCR, GCR, etc.)
- Your RivetKit app
- If you don't have one, see the [Quickstart](/docs/actors/quickstart) page or our [Examples](https://github.com/rivet-dev/rivet/tree/main/examples)
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
### Package Your App
Create a `Dockerfile` in your project root:
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV PORT=8080
CMD ["node", "server.js"]
```
### Build and Push the Image
```bash
docker build -t registry.example.com/your-team/rivetkit-app:latest .
docker push registry.example.com/your-team/rivetkit-app:latest
```
Replace `registry.example.com/your-team` with your registry path. Auth with `docker login` first if needed.
### Set Environment Variables
After creating your project on the Rivet dashboard, select Kubernetes as your provider. You'll be provided `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` environment variables.
Create a `rivetkit-secrets.yaml` for your environment variables:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: rivetkit-secrets
type: Opaque
stringData:
RIVET_ENDPOINT: <your-rivet-endpoint>
RIVET_PUBLIC_ENDPOINT: <your-rivet-public-endpoint>
```
### Deploy to Kubernetes
Create a `deployment.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: rivetkit-app
spec:
replicas: 1
selector:
matchLabels:
app: rivetkit-app
template:
metadata:
labels:
app: rivetkit-app
spec:
# Allow enough time for actors to gracefully stop on SIGTERM.
# The runner waits up to 30m for actors to finish.
# Add buffer for runner shutdown overhead after actors stop.
# See: /docs/actors/versions#graceful-shutdown-sigterm
terminationGracePeriodSeconds: 2100
containers:
- name: rivetkit-app
image: registry.example.com/your-team/rivetkit-app:latest
envFrom:
- secretRef:
name: rivetkit-secrets
```
Apply both manifests:
```bash
kubectl apply -f rivetkit-secrets.yaml
kubectl apply -f deployment.yaml
```
### Connect to Rivet
1. Add a `Service` and Ingress to expose your app externally (e.g. `my-app.example.com`)
2. On the Rivet dashboard, paste your domain with the `/api/rivet` path into the connect form (e.g. `https://my-app.example.com/api/rivet`)
3. Click "Done"
Rivet envoys connect to your app over long-lived WebSockets, and your app's clients (browsers, SDKs) do the same. Default Ingress and cloud load balancer idle timeouts (typically 30 to 60 seconds) drop these connections and cause reconnect storms.
Raise the idle / read / send timeout on every Ingress and load balancer in front of your app to at least 1 hour (`3600` seconds). Examples:
- **NGINX Ingress**: `nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"` and `nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"`
- **AWS Load Balancer Controller (ALB)**: `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`
- **GCE Ingress (GKE)**: set `timeoutSec: 3600` on the `BackendConfig` referenced by the Service.
### Verify
Check that the pod is running:
```bash
kubectl get pods -l app=rivetkit-app
```
Your app should appear as connected on the Rivet dashboard once the pod is ready.
_Source doc path: /docs/deploy/kubernetes_

45
.agents/skills/rivetkit/reference/deploy/railway.md Normal file
View File

@@ -0,0 +1,45 @@
# Deploying to Railway
> Source: `src/content/docs/deploy/railway.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/railway
> Description: Deploy your RivetKit app to Railway.
---
## Steps
### Prerequisites
- [Railway account](https://railway.app)
- Your RivetKit app
- If you don't have one, see the [Quickstart](/docs/actors/quickstart) page or our [Examples](https://github.com/rivet-dev/rivet/tree/main/examples)
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
### Deploy to Railway
1. Connect your GitHub account to Railway
2. Select your repository containing your RivetKit app
3. Railway will automatically detect and deploy your app
See [Railway's deployment docs](https://docs.railway.com/quick-start) for more details.
### Set Environment Variables
After creating your project on the Rivet dashboard, select Railway as your provider. You'll be provided `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` environment variables to add to your Railway service.
See [Railway's environment variables docs](https://docs.railway.com/guides/variables#service-variables) for more details.
### Connect to Rivet
1. In your Railway project, go to **Settings > Networking**
2. Click **Create Custom Domain** then **Create Domain** to generate a Railway domain (e.g. `my-app.railway.app`)
3. On the Rivet dashboard, paste your domain with the `/api/rivet` path into the connect form (e.g. `https://my-app.railway.app/api/rivet`)
4. Click "Done"
Rivet envoys connect to your app over long-lived WebSockets, and your app's clients (browsers, SDKs) do the same. Railway's HTTP proxy supports WebSockets, but if you front your app with your own reverse proxy (NGINX, Caddy, etc.) inside the Railway service, raise its idle / read timeout to at least 1 hour (`3600` seconds). Default proxy timeouts (typically 30 to 60 seconds) drop these connections and cause reconnect storms.
### Configure Sleeping & Multi-Region (Optional)
- [Enable App Sleeping](https://docs.railway.com/reference/app-sleeping) to reduce costs when idle
- [Configure Multi-Region](https://docs.railway.com/reference/deployment-regions) to deploy closer to your users
_Source doc path: /docs/deploy/railway_

144
.agents/skills/rivetkit/reference/deploy/rivet-compute.md Normal file
View File

@@ -0,0 +1,144 @@
# Deploying to Rivet Compute
> Source: `src/content/docs/deploy/rivet-compute.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/rivet-compute
> Description: Run your backend on Rivet Compute.
---
Using an AI coding agent? Open **Connect** on the [Rivet dashboard](https://dashboard.rivet.dev), select **Rivet Cloud**, and paste the one-shot prompt into your agent and have it connect with Rivet Compute for you.
## Steps
### Prerequisites
- Your RivetKit app
- If you don't have one, see the [Quickstart](/docs/actors/quickstart) page or our [Examples](https://github.com/rivet-dev/rivet/tree/main/examples)
- A [Rivet Cloud](https://dashboard.rivet.dev) account and project
- Docker running locally
### Create a Dockerfile
Add a `Dockerfile` to your project root that builds and runs your RivetKit server:
```dockerfile @nocheck
FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
CMD ["node", "src/server.js"]
```
### Get Your Cloud Token
1. Open the [Rivet dashboard](https://dashboard.rivet.dev) and navigate to your project
2. Click **Connect** and select **Rivet Cloud**
3. Copy the **`RIVET_CLOUD_TOKEN`** value shown
### Deploy
Run the deploy command from your project root. The token is saved to `~/.rivet/credentials`, so later deploys can omit it.
```bash
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.
### Optionally Add CI
After local deploys work, install the GitHub Actions workflow that deploys on every push and pull request:
```bash
npx @rivetkit/cli setup-ci
```
This writes `.github/workflows/rivet-deploy.yml`. Add your token as a repository secret to enable it:
```bash
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](/docs/cli) for all commands.
### Monitor Deployment
The dashboard shows live status as Rivet Compute provisions your backend:
| Status | Description |
| --- | --- |
| Initializing | Starting the runtime environment |
| Deploying | Pulling and launching your container |
| Binding | Connecting the runner to the network |
| Ready | Deployment complete |
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`.
```bash
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.
```bash
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:
```bash
npx @rivetkit/cli logs --follow
```
Each formatted line is printed as `<timestamp> [] <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:
```bash
# 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.
_Source doc path: /docs/deploy/rivet-compute_

50
.agents/skills/rivetkit/reference/deploy/supabase.md Normal file
View File

@@ -0,0 +1,50 @@
# Deploying to Supabase Functions
> Source: `src/content/docs/deploy/supabase.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/supabase
> Description: Deploy an existing Rivet project to Supabase Edge Functions.
---
This guide covers deploying an existing Rivet project to Supabase Edge Functions.
## Prerequisites
- [Supabase project](https://supabase.com/)
- [Supabase CLI](https://supabase.com/docs/guides/cli) configured for your project
- A Rivet namespace from the [Rivet Dashboard](https://dashboard.rivet.dev/) or a self-hosted Rivet Engine
## Steps
### Set up your project
Follow the [Supabase Functions Quickstart](/docs/actors/quickstart/supabase) to set up your project locally.
### Set Secrets
Set your Rivet connection values as Supabase secrets. Find `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` in the [Rivet Dashboard](https://dashboard.rivet.dev/) under **Settings → Namespace → Advanced → Backend Configuration** and copy them in.
```sh
npx supabase secrets set \
RIVET_ENDPOINT=https://your-namespace:sk_...@api.rivet.dev \
RIVET_PUBLIC_ENDPOINT=https://your-namespace@api.rivet.dev
```
### Deploy
Make sure the function has the `deno.json` import map from the [quickstart](/docs/actors/quickstart/supabase) that points `rivetkit` at `@rivetkit/supabase`. It keeps the deploy to the WebAssembly runtime; without it the deploy pulls Rivet's native engine and fails with a `413` (request too large).
```sh
npx supabase functions deploy rivet
```
### Register the Serverless Runner URL
After deploy, set the function URL with the `/api/rivet` path as the serverless runner URL in Rivet. For a function named `rivet`, this is usually `https://your-project.functions.supabase.co/functions/v1/rivet/api/rivet`.
## Related
- [Supabase Functions Quickstart](/docs/actors/quickstart/supabase)
- [Deploying to Cloudflare Workers](/docs/deploy/cloudflare)
- [SQLite](/docs/actors/sqlite)
_Source doc path: /docs/deploy/supabase_

138
.agents/skills/rivetkit/reference/deploy/vercel.md Normal file
View File

@@ -0,0 +1,138 @@
# Deploying to Vercel
> Source: `src/content/docs/deploy/vercel.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/vercel
> Description: Deploy your Next.js Rivet app to Vercel.
---
This guide assumes a Next.js app.
## Prerequisites
- [Vercel account](https://vercel.com/)
- A Next.js Rivet app
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
## Steps
### Set up your project
Follow the [Next.js Quickstart](/docs/actors/quickstart/next-js) to set up your project.
### Verify Your Project Structure
Your Next.js project should have the following structure:
- `src/app/api/rivet/[...all]/route.ts`: RivetKit route handler
- `src/rivet/registry.ts`: Actor definitions and registry
The route handler sets `maxDuration` to extend the serverless function timeout so long-lived actor requests are not cut short:
```ts src/app/api/rivet/[...all]/route.ts @nocheck
import { toNextHandler } from "@rivetkit/next-js";
import { registry } from "@/rivet/registry";
export const maxDuration = 300;
export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } = toNextHandler(registry);
```
### Set Environment Variables
Set `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` in your Vercel project settings using the URL auth format:
```
RIVET_ENDPOINT=https://my-namespace:sk_****@api.rivet.dev
RIVET_PUBLIC_ENDPOINT=https://my-namespace:pk_****@api.rivet.dev
```
`RIVET_ENDPOINT` uses the secret token for server-side access. `RIVET_PUBLIC_ENDPOINT` uses the publishable token and tells the metadata endpoint what connection info to provide to clients.
### Deploy to Vercel
1. Connect your GitHub repository to Vercel
2. Vercel will deploy your app
### Configure Preview Deployments (Recommended)
Add a GitHub action to automatically create isolated Rivet namespaces for each PR:
1. Add these secrets to your GitHub repository:
- `RIVET_CLOUD_TOKEN`: Get from [Rivet Dashboard](https://dashboard.rivet.dev) → Settings → Advanced → Cloud API Tokens
- `VERCEL_TOKEN`: Get from [Vercel Account Settings](https://vercel.com/account/tokens)
2. Create `.github/workflows/rivet-preview.yml`:
```yaml
name: Rivet Preview
on:
pull_request:
types: [opened, synchronize, reopened]
push:
branches: [main]
concurrency:
group: rivet-preview-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
rivet-preview:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: rivet-dev/preview-namespace-action@v1
with:
platform: vercel
rivet-token: ${{ secrets.RIVET_CLOUD_TOKEN }}
vercel-token: ${{ secrets.VERCEL_TOKEN }}
```
## Troubleshooting
```
Error: ENOENT: no such file or directory, mkdir '.../rivetkit/.../state'
```
**Cause:** The `RIVET_ENDPOINT` environment variable is not configured. RivetKit falls back to the file system driver, which fails in Vercel's read-only serverless environment.
**Solution:** Ensure `RIVET_ENDPOINT` is set with your Rivet endpoint using the URL auth format:
```
RIVET_ENDPOINT=https://my-namespace:sk_****@api.rivet.dev
```
If using the [preview-namespace-action](https://github.com/rivet-dev/preview-namespace-action), this is configured automatically.
The `/api/rivet/metadata` endpoint returns data but `clientEndpoint`, `clientNamespace`, and `clientToken` are missing.
**Cause:** The `RIVET_PUBLIC_ENDPOINT` environment variable is not configured. This tells the metadata endpoint what connection info to provide to clients.
**Solution:** Set `RIVET_PUBLIC_ENDPOINT` with the publishable token (for client access):
```
RIVET_PUBLIC_ENDPOINT=https://my-namespace:pk_****@api.rivet.dev
```
If using the [preview-namespace-action](https://github.com/rivet-dev/preview-namespace-action), this is configured automatically.
Rivet fails to connect to your Vercel deployment with a 401 error mentioning "Authentication Required".
**Cause:** [Vercel Deployment Protection](https://vercel.com/docs/security/deployment-protection) is blocking requests from Rivet.
**Solution:**
1. Create a bypass secret in your Vercel project settings
2. In Rivet, go to **Settings > Providers**
3. Click the three dots on your provider and select **Edit**
4. Click **Add Header** and add `x-vercel-protection-bypass` with your bypass secret
If using the [preview-namespace-action](https://github.com/rivet-dev/preview-namespace-action), this is configured automatically.
## Related
- [Next.js Quickstart](/docs/actors/quickstart/next-js)
- [Self-Hosting](/docs/general/self-hosting)
_Source doc path: /docs/deploy/vercel_

96
.agents/skills/rivetkit/reference/deploy/vm-and-bare-metal.md Normal file
View File

@@ -0,0 +1,96 @@
# Deploying to VMs & Bare Metal
> Source: `src/content/docs/deploy/vm-and-bare-metal.mdx`
> Canonical URL: https://rivet.dev/docs/deploy/vm-and-bare-metal
> Description: Deploy your RivetKit app to any Linux VM or bare metal host.
---
## Steps
### Prerequisites
- A Linux VM or bare metal server with SSH access
- Your RivetKit app
- If you don't have one, see the [Quickstart](/docs/actors/quickstart) page or our [Examples](https://github.com/rivet-dev/rivet/tree/main/examples)
- Access to the [Rivet Cloud](https://dashboard.rivet.dev/) or a [self-hosted Rivet Engine](/docs/general/self-hosting)
### Upload Your App
- Build your RivetKit app locally
- Copy the build output to your server (example):
```bash
scp -r ./dist user@server:/opt/rivetkit-app
```
Place the files somewhere readable by the service user, such as `/opt/rivetkit-app`.
### Set Environment Variables
After creating your project on the Rivet dashboard, select VM & Bare Metal as your provider. You'll be provided `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` environment variables to use in the next step.
### Create the systemd Service
Create `/etc/systemd/system/rivetkit-app.service`:
```ini
[Unit]
Description=RivetKit App
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/rivetkit-app
ExecStart=/usr/bin/node server.js
Restart=on-failure
Environment=RIVET_ENDPOINT=<your-rivet-endpoint>
Environment=RIVET_PUBLIC_ENDPOINT=<your-rivet-public-endpoint>
[Install]
WantedBy=multi-user.target
```
Replace the environment values with those from the Rivet dashboard and adjust paths to match your deployment.
### Start the Service
Reload systemd units and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now rivetkit-app.service
```
### Connect to Rivet
1. Ensure your server is accessible via a public URL (e.g. `https://my-app.example.com`)
2. On the Rivet dashboard, paste your URL with the `/api/rivet` path into the connect form (e.g. `https://my-app.example.com/api/rivet`)
3. Click "Done"
If you front your app with a reverse proxy or load balancer (NGINX, HAProxy, Caddy, AWS ALB/NLB, etc.), raise its idle / read timeout to at least 1 hour (`3600` seconds). Rivet envoys connect to your app over long-lived WebSockets, and clients (browsers, SDKs) do the same. Default proxy timeouts (typically 30 to 60 seconds) drop these connections and cause reconnect storms.
Examples:
- **NGINX**: `proxy_read_timeout 3600s;` and `proxy_send_timeout 3600s;` in the relevant `location` block.
- **HAProxy**: `timeout client 1h` and `timeout server 1h` in the matching frontend / backend.
- **AWS ALB / NLB**: set the load balancer attribute `idle_timeout.timeout_seconds = 3600`.
## Operating
### Restart
Restart the service after deploying new builds or environment changes:
```bash
sudo systemctl restart rivetkit-app.service
```
### Logs
Follow realtime logs when debugging:
```bash
sudo journalctl -u rivetkit-app.service -f
```
_Source doc path: /docs/deploy/vm-and-bare-metal_