deploy anything to your Pi

Deploy to your Raspberry Pi with one command.

rpi-deploy builds and runs your Docker Compose projects on the Pi — over plain SSH. No registry, no Kubernetes, no YAML pipelines.

$ npm install -g rpi-deploy

prebuilt binaries for Linux x64/arm64 · Windows x64 · builds from source elsewhere ·

~/rpi-deploy-site

$ rpi deploy
░░
▒▒▒▒    r p i
▓▓▓▓▓▓  deploy · rpi-deploy-site
▓▓▓▓
██
▸ agent 0.27.0 (api v1)
✓ source access (0.4s)
▸ deployment 3f9c21a4-8b7e-4c2a-9f1d-2e6a5b0c7d84 started; streaming logs:
✓ fetch (1.4s)
fetched 4f2a91c8d3e05b7a16f4c92d8be7130a5c6f8e42
runtime env: 6 vars over 1 service(s)
✓ build (38.2s)
✓ start (2.1s)
✓ health (1.2s)
✓ route (0.6s)
✓ gc (0.3s)
▸ deployed ✓ rpi-deploy-site  →  rpi.iiskelo.com · 1 service (44.9s)

claude code plugin

Your agent reads the docs, not its training data

Two skills ship with the tool and load straight into Claude Code, so the agent you already deploy with works from the real CLI and rpi.toml surface instead of guessing at flags.

rpi-cli/SKILL.md

deploys · secrets and secret groups · environment overlays · logs and stats · agent setup · connection troubleshooting

~320 tok resident · ~7.1k when it fires
rpi-toml/SKILL.md

schema 1 fields · ingress and health checks · rpi.<env>.toml overlays · config variables · the RPI_* runtime set

~220 tok resident · ~7k when it fires

540 tokens sit in every session — that is the whole standing cost. A skill's body loads only when it fires.

$ claude plugin marketplace add khmilevoi/rpi-deploy
$ claude plugin install rpi@rpi

how it works

One binary, two roles, one SSH connection

your machine

rpi CLI

Run rpi deploy from your project. Works from a laptop or CI.

raspberry pi

rpi agent

A systemd daemon clones your repo, builds the Compose stack, allocates a stable port.

the internet

your app, live

Health-checked and reachable — via Cloudflare Tunnel or your own ingress.

features

Everything a deploy needs, nothing it doesn't

Latest-wins deploy queue

Push again mid-deploy and it queues — only the newest waiting deploy survives. rpi deploy --cancel aborts the running one.

Encrypted secrets

Env files and secret files (certs, keys) delivered as sealed bundles — plus reusable secret groups, pushed once and inherited by every branch preview.

Cloudflare Tunnel ingress

A public hostname for your app without opening a single port.

Health checks

HTTP or TCP probes gate every deploy — a build that fails its probe never gets routed.

Stable port allocation

Each project keeps its host port across deploys. No conflicts.

Survives reboots

Your public service comes back on its own after a Pi power-cycle (restart: unless-stopped) — and a deliberate rpi stop stays stopped.

Logs, stats, lifecycle

rpi logs -f, rpi stats -w for a live dashboard — CPU / memory / temp cards with mini charts and per-service bars, start/stop/restart — without leaving your shell.

One-off commands

Migrations, backups, invites — declared in rpi.toml, run in the container. Output streams back live and in full, so rpi command migrate > migrate.log captures exactly what ran.

Installs in seconds

Pulls a prebuilt binary for Linux x64/arm64 and Windows x64 via npm — no toolchain, no compile step, no Docker on your machine (anything else builds from source).

Client-triggered updates

rpi upgrade brings the Pi's agent up to your CLI's version over SSH — download, SHA-256 verify, atomic swap, restart — no manual SSH session.

Live deploy pipeline

Each stage — fetch, build, start, health, route, gc — collapses to a timed summary as it finishes, with a service count in the final stamp.

Deploy-key preflight

First deploy of a private repo won't fail on a missing key — rpi registers a read-only GitHub deploy key for you, or shows it and waits.

Environment overlays

rpi deploy --env <name> spins up a shared test environment or an ephemeral per-branch preview from an rpi.<env>.toml overlay — its own hostname, an optional TTL that self-destructs it, and a one-time on_create hook.

Config variables & runtime env

Any string in rpi.toml can reference ${YOUR_VAR} from --vars, or a resolver input like ${git.branch} / ${env.slug} — and every container gets the RPI_* set (project, environment, branch, hostname, host port, commit sha) without configuring anything.

quick start

Zero to deployed in four steps

1 Install the CLI on your machine

$ npm install -g rpi-deploy
# prebuilt binary, no toolchain
$ rpi --version
rpi 0.27.0

2 Set up the Pi

$ sudo npm install -g rpi-deploy # on the pi
$ sudo rpi agent setup # on the pi
$ rpi setup # on your machine
▸ saved profile 'home' to /home/you/.config/pi/config.toml

3 Describe your project

# rpi init scaffolds this — excerpt below, full file via ⧉:
[project]
name = "my-app"
[ingress]
hostname = "my-app.example.com"
service = "web"
port = 3000

4 Ship it

$ rpi deploy
✓ build (38.2s)
✓ health (1.2s)
▸ deployed ✓ rpi-deploy-site  →  rpi.iiskelo.com · 1 service (44.9s)