hive · docs

A wrangler-shaped CLI for celld — Deno's self-hosted, distributed Durable Objects daemon. Bring your existing Worker; hive tells you if it runs on celld, then deploys and runs it on your own hardware.

Go, stdlib only. Single static binary, zero dependencies, instant cold start.

Quickstart

What you need

• An S3-compatible bucket with conditional writes + read-after-write consistency (Cloudflare R2, AWS S3, Tigris qualify; B2/MinIO/Spaces do not), and its credentials.
• A box to run nodes on: Linux (amd64/arm64) or macOS (arm64). Docker on the box if you want the supervised backend.
• celld installed wherever you deploy from (curl -fsSL https://celld.dev/install.sh | sh), plus esbuild on PATH for deploys.

Cloudflare is optional: cf login/init/cf tunnel automate R2 + Tunnel + DNS, but any S3 credentials and any reverse proxy (caddy, nginx, your own tunnel) work just as well. On exe.dev, hive exe handles VMs, proxy, and domains instead.

Install

curl -fsSL https://hive.butttons.dev/setup.sh | bash

Installs the latest release binary to ~/.local/bin/hive (checksum-verified). Override the destination with HIVE_INSTALL_DIR.

Or build from source:

CGO_ENABLED=0 go build -o hive .

Cross-compiles to GOOS/GOARCH = linux/amd64, linux/arm64, darwin/arm64 — same targets as celld.

First deploy

hive add myapp            # scaffold app, allocates a free port
cd myapp

# credentials: either export AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY /
# S3_ENDPOINT / AWS_REGION / CELLD_BUCKET yourself, or provision with:
hive init --bucket mybucket --access-key ... --secret-key ... --endpoint ...

hive deploy               # tsc → celld deploy → restart node → health gate
curl http://127.0.0.1:<port>/

There is no watch mode or HMR — the restart is the reload. The loop is edit → hive deploy → curl.

Config model

Two files per app, same directory:

• wrangler.jsonc — pristine, celld-legal keys only (name, main, compatibility_date, durable_objects, migrations, vars, assets, services, …). This is the deploy contract handed to celld untouched. celld hard-fails on anything else.
• package.json — a "hive" block for everything celld rejects:

{
  "hive": { "port": 8101, "domain": "app.example.com", "server": "user@box", "dir": "/opt/apps/myapp", "backend": "docker" }
}

port is required. domain, server, dir, backend are optional (local-only apps skip them). When server is set, dir is the absolute path of the app directory on the server; if omitted, the local path is used verbatim, which only works when the box shares the same filesystem layout.

Monorepos

Run hive from a workspace root to operate on the whole fleet. Discovery order:

1. pnpm-workspace.yml / pnpm-workspace.yaml packages: globs.
2. Root package.json workspaces field (array or {"packages":["..."]} object).

A directory counts as a hive app only if its package.json contains a "hive" block. Patterns support a single trailing /* (e.g. apps/*).

hive status and hive ui show fleet views from a workspace root and single-app views from an app dir. hive deploy all deploys every app sequentially, continuing past failures. --filter <name> matches the app's package.json name or directory basename and operates on one app even from the root. If no workspace file exists, --packages <glob> enumerates apps manually.

Environment variables

Commands

Every command takes --json and prints machine-readable output. Agents are the primary user.

hive init credential chain

In order — first match wins:

1. --access-key + --secret-key + --endpoint flags — zero Cloudflare calls, works with any S3 provider.
2. Reuse from a sibling app: an existing ~/.config/hive/<app>.env with a matching CELLD_BUCKET.
3. Cloudflare path: bucket create (if missing) + S3 key mint. The mint needs CLOUDFLARE_API_TOKEN with API Tokens Edit; OAuth tokens can't mint keys (Cloudflare's self-managed OAuth catalog has no API Tokens scope).
4. Otherwise: a deep link to the R2 S3-keys page; paste the pair with --access-key/--secret-key.

hive cf login

Self-managed Cloudflare OAuth (authorization code + PKCE, no client secret). Default public client ID is compiled in; override with HIVE_CF_CLIENT_ID (register your own client for production use). Scopes: argotunnel.write dns.write zone.read workers-r2.write. Tokens live at ~/.config/hive/auth.json (0600) and refresh automatically. --export prints export CLOUDFLARE_API_TOKEN=… instead of saving.

Running nodes

• process (default): celld as a detached process, logs to .hive/node.log, down = SIGTERM (celld drains gracefully). Zero moving parts; no supervisor — a reboot leaves the node down until the next hive up.
• docker (--docker or "backend": "docker"): node runs as container hive-<app> from the official ghcr.io/denoland/celld:<version> image (pulled on demand, pinned to the local celld version), published on 127.0.0.1:<port>, --restart unless-stopped, --stop-timeout 60 (celld 0.4.0 needs up to 40s for graceful shutdown), config drift detected by a label hash → recreate. docker stop is the same graceful drain.

Supervise containers yourself? examples/docker-compose.yml runs a node from the official ghcr.io/denoland/celld image plus a cloudflared sidecar; hive env --tunnel > .env generates its credentials and deploys become hive deploy --no-restart && docker compose restart <app>.

Remote operation & CI

Set "server": "user@box" in the hive block and commands proxy to the hive binary on the box over SSH (ssh box hive <cmd> --local). No RPC protocol; the same backends run there. celld deploy itself is bucket-direct from anywhere — only restart and health checks touch the box. --local forces local operation even when server is set.

When the server's app directory differs from the local one, set "dir": "/absolute/path/on/server" in the hive block. It must be absolute (no ~). On deploy/up, hive creates the directory and syncs package.json + wrangler.jsonc there before running the remote command. down and status also use dir when set.

Box setup: hive bootstrap installs hive + celld at ~/.local/bin on the server (re-run to upgrade). Add docker yourself if wanted. Credentials sync over SSH as ~/.config/hive/<app>.env (0600).

CI: a stock GitHub-hosted runner runs hive deploy; it reaches the box via SSH through the Cloudflare Tunnel (hive cf tunnel --ssh adds the ssh.<domain> ingress rule; sshd bound to loopback, cloudflared as SSH ProxyCommand). Secrets: bucket creds, SSH key, tunnel token.

Going to production

Starting from a plain index.ts + wrangler.jsonc, the whole journey:

hive init                   # one-time: port + bucket credentials
# point the app at a box in package.json:
#   "hive": { "port": 8101, "server": "user@box", "dir": "/opt/apps/myapp", "domain": "app.example.com" }
hive bootstrap              # one-time: hive + celld on the box
hive deploy                 # ship, restart, health-gate — over ssh

Then pick an ingress — all three end at the same 127.0.0.1:<port> listener:

• exe.dev: hive exe share && hive exe domain — the VM's front door does TLS.
• Cloudflare Tunnel: hive cf tunnel, then install cloudflared on the box with the printed token — zero inbound ports.
• Anything else: reverse-proxy 127.0.0.1:8101 yourself (caddy, nginx, …).

Updating is the same command forever: edit index.ts, hive deploy, done — new version ID, node restart, health gate before it reports ok. CI is a stock GitHub-hosted runner with bucket creds + an SSH key running hive deploy; see Remote operation for the tunnel-secured SSH variant.

exe.dev

hive exe drives the exe.dev control plane over its SSH CLI. exe.dev VMs ship with a public hostname, TLS, and an HTTPS front door, so the Cloudflare Tunnel is unnecessary there — the front door is the ingress. Full flow for a fresh VM:

# hive block: { "port": 8101, "server": "mybot.exe.xyz",
#               "dir": "/home/exedev/apps/mybot", "domain": "mybot.example.com" }
hive exe new mybot        # create the VM, wait for DNS
hive bootstrap            # install hive + celld on it
hive deploy               # ship, restart, health-gate over ssh
hive exe share            # https://mybot.exe.xyz → :8101, public (or --private)
hive exe domain           # mybot.example.com live: DNS-only CNAME + registration

exe domain uses your Cloudflare credentials to create the CNAME and hard-requires proxied: false — exe.dev terminates TLS itself and orange-cloud records break it. Without cf credentials it prints the exact record to create and exits; re-run after creating it. Registration is verified via exe.dev's domain ls and retried, since their resolver lags yours.

The --private share mode keeps the proxy behind exe.dev login — the right default for internal tools.

Security notes

• Bucket credentials = full fleet control (deployments, cell replicas, ownership records, node leases). Keep them in env vars or ~/.config/hive/*.env — never in the repo.
• celld's internal/operator listener is unauthenticated. It never leaves loopback; the public listener binds 127.0.0.1 behind your proxy/tunnel.
• Run nodes with --trust-forwarded-headers (hive does) so request.url keeps the public scheme/host.