rivet-deploy-image

Original：🇺🇸 English

Translated

Deploy a Docker image to a Rivet Cloud cluster through the Rivet MCP server, or roll a cluster back to an earlier build. Use when asked to deploy, ship, release, or roll back an app on a Rivet cluster and a shell with Docker is available.

12installs

Sourcerivet-dev/skills

Added on2026-10-22

NPX Install

npx skill4agent add rivet-dev/skills rivet-deploy-image

SKILL.md Content

View Translation Comparison →

Deploy an image to a Rivet cluster

A deploy is a local build, one upload, and two Code Mode operations run through the

execute

tool. It needs Docker and a shell. It does not need the Rivet CLI or any other login.

Before starting

Confirm the session can deploy. If
```
search
```
does not list
```
rivet.deploy.prepare
```
, the session is read-only or is pinned to a project or namespace, and the deploy cannot run from here. Say so instead of retrying.
Pick the cluster. Run
```
return (await rivet.cloud.v2.clusters.list()).items;
```
in
```
execute
```
and use the
```
cluster
```
field of the one to deploy to, which is its name. On a connection pinned to a cluster,
```
rivet.context()
```
reports it, and
```
cluster
```
is left out of every call below.

Steps

Build and measure the image in the shell. The platform must be

linux/amd64

.

sh

docker build --platform linux/amd64 -t app .
docker image save app -o image.tar
wc -c < image.tar                        # content_length
openssl md5 -binary image.tar | base64   # content_md5

The tarball must be 5 GiB or smaller. Measure the exact file that will be uploaded, because the build fails verification when either value differs.

Register the build.

js

return await rivet.deploy.prepare({
	cluster: "my-cluster",
	image: "app:latest",
	content_length: 48213504,
	content_md5: "1B2M2Y8AsgTpgAmY7PhCfg==",
});

content_length

is a number, not a string. Pass

file

when the tarball is not named

image.tar

. Keep the returned

build_id

.

Run the returned
```
upload
```
command in the shell, unchanged. It is a curl command against a presigned URL that is good for that one tarball until
```
expires_at
```
, so it carries no Rivet credentials.
Roll out, repeating until
```
done
```
is
```
true
```
.
js
```
return await rivet.deploy.rollout({ cluster: "my-cluster", build_id: "<build_id>" });
```
Each call advances one step and returns immediately, so call it again while
```
done
```
is
```
false
```
. See
```
references/rollout.md
```
for each step, the errors, and how to roll back.
Report the
```
build_id
```
and the
```
endpoints
```
from the final result to the user. The
```
build_id
```
is what a later rollback needs.

Rules

Never rebuild or re-upload to retry a rollout. Call
```
rivet.deploy.rollout
```
again with the same
```
build_id
```
.
Use
```
rivet.deploy.*
```
for the whole deploy. Do not drive
```
rivet.cloud.v2.builds.*
```
or
```
rivet.cloud.v2.runnerPools.upsert
```
by hand, because an upsert replaces the pool's settings wholesale and would drop its allowlist.
Do not guess a
```
cluster
```
,
```
region
```
, or
```
pool
```
name. List them first.