Skip to content
Getting started / Deploy

Getting started

Deploy

Deploy a Worker to Rivet Cloud with orange deploy, or self-host its Docker image on any cloud or on your own servers.

Your Worker ships as a standard Docker image, so it runs on any cloud and on your own servers. Rivet Cloud is the quickest path. To run everything yourself, see Self-host.

  • AWS
  • Google Cloud
  • Azure
  • Rivet Cloud
  • Your servers

Deploy to Rivet Cloud

Rivet runs the cluster for you on AWS or Google Cloud, in the region you choose. orange deploy builds your Worker into a Docker image, uploads it, and rolls a runner pool out to it.

orange deploy builds an image of your Worker, uploads it, and rolls a runner pool out to it on a Rivet cluster

orange deploy builds an image of your Worker, uploads it, and rolls a runner pool out to it on a Rivet cluster

You need Docker running, a Rivet Cloud cluster, and a Worker project with its packages installed. These steps deploy examples/hello-durable-object.

  1. Sign in

    Approve the code in the browser that opens.

    orange login
    Your one-time code: ABCD-EFGH
    Opened https://… in your browser.
    Waiting for approval…
    Signed in as you@example.com.
    Next: orange link --cluster <name>
  2. Run this in the Worker’s directory.

    orange link --cluster my-cluster
    Linked cluster my-cluster in /home/me/hello-durable-object/.rivet/project.json.
    Next: orange deploy
    Run orange mcp to connect your coding agent to the Rivet MCP for cluster my-cluster.
  3. Deploy

    orange deploy prints each stage after Docker’s build output.

    orange deploy
    Deploying hello-durable-object to cluster my-cluster, region <region>, pool default
    Building hello-durable-object:20261112-093000 for linux/amd64…
    Uploading build <build-id> (427.8 MiB)…
    Preparing build <build-id>. This takes a few minutes…
    ✓ Build <build-id> ready
    Creating pool default with build <build-id>…
    ✓ Deployed hello-durable-object:20261112-093000 to pool default in <region>
      Build   <build-id>
      URL     <pool URL>

    Run orange deploy again to roll out each new version.

  4. Call the Worker

    The pool’s URL serves your Worker.

    curl <pool URL>/alice
    {"greeting":"Hello, alice!","visits":1}

Self-host

Run the same image on your own cloud or servers. You run two parts: the control plane, which is the Rivet Engine, and your Worker nodes, which connect out to it.

On your own server, orange serve runs your Worker and connects out to your Rivet Engine

On your own server, orange serve runs your Worker and connects out to your Rivet Engine

  1. Build the image

    orange deploy --dry-run writes the build and prints the docker commands for your Worker. It needs no sign-in.

    orange deploy --dry-run --outdir out
    docker build --platform linux/amd64 -f out/Dockerfile -t hello-durable-object:20261112-093000 out/context

    Push the image to a registry that your servers can pull from.

  2. Deploy the control plane

    The Rivet Engine schedules your Durable Objects onto your nodes and routes requests to them. Deploy it once with Rivet’s self-hosting guide, which covers Kubernetes, AWS ECS, Docker Compose, VMs, Hetzner, Railway, and Render.

    Then create the default node pool, as in Rivet’s node guide. The control plane refuses a node whose pool does not exist.

  3. Run your Worker nodes

    Each node is a container of your image. Point it at the control plane’s endpoint, with its namespace and token.

    docker run --rm -p 8080:8080 \
      -e 'RIVET_ENDPOINT=https://<namespace>:<token>@<engine-host>' \
      hello-durable-object:20261112-093000
    orange serve listening on http://0.0.0.0:8080

    Run as many nodes as you need, on any platform that keeps a container running. Rivet has node guides for Kubernetes, AWS ECS, Docker Compose, VMs, Hetzner, Railway, and Render.

  4. Call the Worker

    curl localhost:8080/alice
    {"greeting":"Hello, alice!","visits":1}

Bring your own cloud

With BYOC, Rivet runs the cluster in your own AWS, Google Cloud, or Azure account. A BYOC cluster is a Rivet Cloud cluster, so Deploy to Rivet Cloud works as written. See Rivet’s BYOC guide.

Variables and secrets

Pass secrets in a file and variables as flags. Your Worker reads both from env, such as env.API_KEY.

orange deploy --secrets-file .dev.vars --var LOG_LEVEL:debug

Never put a secret in vars. Everything in vars goes into the image.

Deploy from CI

Make a cluster token in the Rivet dashboard: open the cluster, then Settings → API tokens. Give it the Read and Deploy scopes, and set it in RIVET_CLOUD_TOKEN. A cluster token cannot create a runner pool, so the pool must exist first. Create it in the dashboard, or deploy one time with orange login.

RIVET_CLOUD_TOKEN=<cluster token> orange deploy --cluster my-cluster
AI context Sign-in, every flag, secret rules, refused values, rollback, failed deploys, and self-host details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Sign in

orange login, logout, whoami, link, and unlink work like the same Rivet CLI commands and use the same files, so a rivet login session and a rivet link --cluster link work with Orange too. openorange and open-orange are the same command as orange.

FileWhat it holds
~/.rivet/credentialsThe login session, refreshed as needed
.rivet/project.jsonThe cluster and organization of this directory. Commands in it and below it use this cluster, because they search upward for the file.

After orange link, run orange mcp to connect your coding agent to the Rivet MCP for the linked cluster. It prints the command for the agent you use and changes no configuration. orange mcp --json gives the command for every agent. orange link prints its last line, the orange mcp reminder, until an agent configuration has the Rivet MCP.

Orange finds credentials in this order:

  1. --token
  2. RIVET_CLOUD_TOKEN
  3. The login session
  4. A Cloud API token in ~/.rivet/credentials
Cluster tokens for CI

In CI, name the cluster with --cluster or RIVET_CLUSTER. The cluster token in RIVET_CLOUD_TOKEN needs these scopes:

Token scopeWhen
Read and DeployAlways
Secrets write (rivet:cluster:secrets:write)When the deploy passes --var, --secret, or --secrets-file

What happens during a deploy

  1. Orange reads the cluster’s regions. This checks the token and the cluster before anything is built.
  2. Orange runs build.command from the Wrangler configuration, if there is one, on the machine that deploys, as wrangler deploy does.
  3. docker build --platform linux/amd64 builds the image, and docker image save writes it to a tarball. Rivet clusters take images up to 5 GiB.
  4. Orange registers a build, uploads the tarball to the build’s upload URL, and waits until the build is ready. Rivet Cloud prepares a build in 3 to 5 minutes. In a terminal, Orange shows the bytes sent and the upload rate. When the connection drops, or Rivet Cloud or storage answers 408, 429, or 5xx, Orange sends the request again, up to 3 attempts in total.
  5. Orange rolls the runner pool out to the build. With an orange login session, it creates the pool if it does not exist, and prints Creating pool default. With a cluster token, the pool must exist. Every later deploy rolls the same pool out to a new build, and prints Rolling out pool default instead. An existing pool keeps its CIDR allowlist, machine type, and node count unless you pass --machine-type or --node-count.
  6. Orange waits until every node of the pool runs the build, then prints the pool’s public URL.
FailureResult
build.command failsThe deploy stops.
The build failsThe deploy stops before the pool changes.
The pool goes degraded or down during the rolloutThe deploy stops. Orange prints the pool’s reason and the command that rolls the pool back to its earlier build.

--build <id> builds nothing, so it skips steps 2 to 4.

What goes into the image

  • The project directory, without .git, node_modules, .open-orange, .rivet, .wrangler, .dev.vars*, .env, and .env.*.
  • The Worker’s packages, bundled into its entry file on the machine that deploys, so install them first. This is how workspace: and file: dependencies work. The image installs nothing for the Worker, so a package that reads its own files at runtime cannot find them.
  • The Orange build that runs the command, with its locked dependencies.
  • CMD ["orange", "serve", ...] with your --config and -e values.

The image holds no Rivet credentials. The cluster sets RIVET_ENDPOINT, RIVET_TOKEN, RIVET_NAMESPACE, and RIVET_POOL when it starts a runner, and orange serve connects to the cluster as a runner.

The build goes to .open-orange/deploy/, or to --outdir <dir>.

Variables and secrets in detail

SourceReaches the deployed Worker
vars in the Wrangler configurationYes, inside the image
--var NAME:valueYes, in the runner pool’s environment. Replaces a vars entry of the same name.
--secrets-file <path>Yes. Orange rolls each entry out as a cluster secret, and the pool’s environment names it. The file is a JSON object or .env lines, as for wrangler secret bulk.
--secret KEY[=SECRET_NAME]Yes. env.KEY reads a secret the cluster already holds, named KEY unless you give SECRET_NAME, as with rivet deploy --secret.
.dev.vars and .env entriesOnly through --secrets-file .dev.vars. They never enter the image.

A secret managed with the rivet CLI:

rivet cluster secret set DATABASE_URL
orange deploy --secret DATABASE_URL

Where a secret’s value goes

  • It never goes in an argument, the image, or Orange’s output.
  • Orange sends it only to the Rivet Cloud API, which stores it encrypted.
  • The cluster gives it to each runner when the runner starts.

What a deploy changes

  • A deploy without --var, --secret, or --secrets-file leaves the pool’s variables as they are.
  • --var, --secret, and --secrets-file add to the pool’s variables and keep the rest, as rivet deploy --env does.
  • To remove a variable, run rivet cluster env unset KEY.

How --secrets-file names secrets

  • It names each secret like its variable, as rivet does. API_KEY becomes the cluster secret API_KEY, and rivet cluster secret set API_KEY changes what the Worker reads.
  • Two Workers in one cluster that use the same variable name share one secret. To keep them apart, set each secret under its own name and pass --secret API_KEY=<SECRET_NAME>.
  • A new value rolls every pool that uses the secret. So a deploy that changes a secret rolls the running build one time with the new value, then rolls to the new build.
  • An unchanged value rolls nothing.
Values that Orange refuses

Orange refuses these before it builds or writes anything:

Value or nameWhy
A value with a line break or another control character, such as a PEM keyValues are one line. Encode it with base64 -w0 key.pem, and decode it in the Worker with atob(env.KEY).
A --secrets-file name over 64 charactersA cluster secret’s name holds at most 64.
A secret over 1,024 bytesKeep large material in R2 or KV, and put the key to it in the secret.
An empty value in --secrets-fileAn empty secret is usually a mistake. Give it a value, or remove the line.
A --secret that the cluster does not holdSet it first with rivet cluster secret set, or pass it in --secrets-file.
More than 64 secrets on the cluster, or more than 256 variables or 32 KiB on the poolRivet’s limits.
RIVET_ENDPOINT, RIVET_TOKEN, PORT, RIVET_USER_DATA_*, and the other names Rivet setsRivet sets them on every runner.
A name already used by another binding, such as a KV namespaceA variable cannot replace a binding.
-e selects a Wrangler environment

orange deploy -e staging works as wrangler deploy -e staging: it selects the env.staging block of the configuration. It does not set a variable. Orange rejects an -e value that contains =.

Roll back

Every deploy prints its build ID. To roll a pool back, pass an earlier build with --build:

orange deploy --cluster my-cluster --pool default --build <build-id>

Fix a failed deploy

ResponseMeaning
401The token is missing, invalid, or expired.
403The token’s organization does not own the cluster.
404, cluster not foundThe cluster does not exist, or the token belongs to another organization.
402The organization’s plan or payment method does not cover the pool.
400A value is invalid. Orange prints each field error.

A pool that goes degraded or down stops the deploy, as in What happens during a deploy.

Self-host in detail

The image runs as a runner of your own Rivet Engine. The runner connects out to the Engine, so the Engine does not need to reach the container.

orange deploy --dry-run --outdir out calls no API. Its output ends with the two commands to run:

Self-host
  docker build --platform linux/amd64 -f /home/me/hello-durable-object/out/Dockerfile -t hello-durable-object:20261112-093000 /home/me/hello-durable-object/out/context
  docker run --rm -p 8080:8080 -e 'RIVET_ENDPOINT=https://<namespace>:<token>@<engine-host>' hello-durable-object:20261112-093000

The image name is the Worker’s name, and the tag is the UTC time. Docker’s last step tags the image hello-durable-object:20261112-093000.

orange serve also reads RIVET_TOKEN and RIVET_NAMESPACE when the endpoint URL does not carry them, and RIVET_POOL, which defaults to default. A dry run with --var or --secrets-file adds each one to the docker run command, and passes each secret as a bare -e NAME, so Docker reads the value from your shell.

Options

FlagMeaning
-c, --config <path>Wrangler configuration file. One Worker per deploy.
-e, --env <name>Wrangler environment from the configuration. Not a variable.
--cluster <name>Cluster to deploy to. Default: RIVET_CLUSTER, then the linked cluster. Required.
--org <slug>Organization of the cluster. Default: RIVET_ORG, then the linked organization.
--region <region>Region of the pool. Default: the cluster’s only region. A cluster with several regions needs this flag.
--pool <name>Runner pool. Default: default.
--var <NAME:value>Set a variable in the pool’s environment. Repeat for more. See Variables and secrets.
--secret <KEY[=SECRET_NAME]>Set KEY to a cluster secret the cluster holds. Repeat for more.
--secrets-file <path>Roll out secrets from a JSON object or .env file, and set them on the pool.
--token <token>Rivet Cloud API token. Default: RIVET_CLOUD_TOKEN, then the login session. Prefer the variable, because a flag stays in your shell history. The token selects the organization.
--cloud-api <url>Rivet Cloud API. Default: https://cloud-api.rivet.dev.
--build <id>Roll the pool out to a build that is ready. Orange builds and uploads nothing.
--image <name>Image name recorded on the build. Default: the Worker name.
--tag <tag>Image tag. Default: the UTC time, such as 20261028-213000.
--machine-type <type>Machine type of the pool’s nodes, such as e2-small. The cluster’s plan limits the types.
--node-count <count>Number of nodes in the pool.
--dry-runWrite the build context and print the plan. Orange calls no API.
--outdir <dir>Write Dockerfile and context/ here.

A new pool without --machine-type and --node-count gets the Rivet Cloud defaults. Orange sends neither value.

Dry run and --outdir

--dry-run writes the build and prints the resolved cluster, region, pool, and image, and the docker commands for a self-hosted run. It prints the token as <redacted>. It sends nothing to Rivet Cloud, so it does not check the token.

--outdir <dir> writes Dockerfile and context/ to <dir>. It works with and without --dry-run, as in wrangler deploy --outdir. Unlike Wrangler, Orange refuses a directory that holds files it did not write, because a build context with stale files would go into the image. A later run replaces its own Dockerfile and context/.