Deploy to Fly.io

One command to start

Why this path. Parachute is happiest on your own machine, but a laptop sleeps. Fly.io is one of two "always-on URL" paths we support that still let you own everything — a single container running your hub, with a persistent volume for your vault, all in your Fly account. No tenancy, no shared database, no Parachute-operated cloud sitting between you and your data. (See Deploy to Render for the peer path.)

Same setup as every install. A Fly deploy isn't a different onboarding — it's the same unified flow. Locally you'd run parachute init to get a hub and land in the setup wizard; here, Fly gives you a running, already-exposed hub at a *.fly.dev URL, and you land in the identical wizard at /admin/setup. You'll walk the same Account → Vault steps an operator on a laptop or an EC2 box walks; the wizard's Expose step auto-skips on Fly (the platform already owns the public URL via *.fly.dev), so you go straight to Done. The only Fly-specific bit is grabbing a one-time bootstrap token from the logs to claim admin (step 3).

The script installs flyctl if you don't have it, signs you in if needed, and runs fly launch --copy-config against the repo's fly.toml. First deploy takes about one to two minutes.

What you get

One Fly machine (shared-cpu-1x, 512MB RAM, ~$3.34/month all-in for compute + volume in iad) running hub-as-supervisor — the same architecture you'd run locally, just inside a Fly container. One persistent volume mounted at /parachute for module installs and vault data. HTTPS and a *.fly.dev subdomain included; custom domains attach with one fly certs add command.

Modules are not pre-installed. The container ships with only the hub. After first boot, the admin UI lets you install Vault, Surface (the UI host module, with Notes auto-bootstrapped as the first hosted surface), and Scribe with one click each — they install onto the persistent volume under /parachute/modules, so they survive redeploys.

This is the deploy mirror of the local model: locally, the hub supervises vault, app, and scribe as child processes sharing ~/.parachute/. On Fly, the hub supervises the same children in the same container, sharing the mounted volume. See the v0.6 deploy architecture note for the full shape.

Why Fly vs Render? Both work. Fly is CLI-first (you'll spend more time in a terminal); Render is GUI-first (more clicks, no CLI install needed). Fly is cheaper (~$3.50 vs $7). Fly's volumes are portable — fly volumes snapshot lets you take your data with you. Render's disks don't snapshot-export. Pick whichever fits your operator preferences. See the Fly migration design note for the longer reasoning.

1. Install flyctl + sign in

Why this step. Fly's deploy flow is CLI-driven. There's no equivalent of Render's "Deploy" button — instead, flyctl (their CLI) talks to Fly's API to provision the app, machine, and volume.

If you don't already have flyctl, the deploy script offers to install it for you via Fly's official one-liner. Or install it yourself first:

Then sign in:

This opens your browser to Fly's sign-up / sign-in. Free account, no card required to make one (a card is required before you deploy a paid app, which is everything but the smallest free-tier shapes).

What you should see. flyctl on your PATH. fly auth whoami prints your email.

2. Fork + clone + deploy

Why this step. Fly deploys from a local checkout, not from a GitHub-connected pipeline by default. Fork the repo so future updates can be pulled in cleanly; clone locally so fly launch has the fly.toml + Dockerfile to work from.

The script:

1. Checks for flyctl (skips if you already installed it in step 1).
2. Confirms you're signed in.
3. Runs fly launch --copy-config --yes. Fly generates a unique app name (or use ./scripts/deploy-to-fly.sh my-app-name to pick your own), provisions a shared-cpu-1x 512MB machine in iad, attaches a 1GB volume at /parachute, and kicks off the build.
4. Prints your hub's URL when done.

Region. The default is iad (Virginia, US East) — cheapest tier. To pick a different one, edit primary_region in fly.toml before running the script. Other common picks: sjc (San Jose), lax (Los Angeles), lhr (London), fra (Frankfurt), syd (Sydney). The full list is at Fly's regions docs.

What you should see. Build log streaming. After ~60–100 seconds, "Deployment complete" and a URL like https://your-app-name.fly.dev.

3. Grab the bootstrap token and open setup

Why this step. Hub generates a one-time bootstrap token on first boot and prints it in the startup logs. You'll grab it from fly logs and paste it into the setup wizard to claim admin.

Look for a banner like:

[wizard] ════════════════════════════════════════════════════════════════
[wizard]   PARACHUTE BOOTSTRAP TOKEN
[wizard] ════════════════════════════════════════════════════════════════
[wizard]
[wizard]   parachute-bootstrap-XXXXXXXXXXXXX
[wizard]
[wizard]   → Visit https://YOUR-URL/admin/setup ...

Copy the parachute-bootstrap-XXXXXXXXXXXXX line (prefix + 43-char body). That's your token.

Visit your hub's URL (printed by the deploy script, or run fly status --app your-app-name to find it). You'll land at /admin/setup. Paste the token, choose your admin username + password, click Create Admin. You're in.

The token expires when admin is created OR when the hub machine restarts — so don't navigate away mid-setup. If you lose it, redeploy with fly deploy --app your-app-name and grab the fresh token from the new boot's logs.

What you should see. The setup wizard, now past the Account step (your admin's been created) and ready to walk you through the rest: Vault, Expose, Done. Step 4 covers the remaining wizard screens.

4. Walk the first-boot wizard

Why this step. Your admin account was created in step 3 via the bootstrap-token form. From here it's the same wizard every Parachute install uses — the one a laptop operator reaches via parachute init, just pre-advanced past the account step. It walks through what still needs to be set up once and can't be defaulted: your first vault and how this hub is reached.

1. Vault. Create a fresh vault (defaults to default — any short name of lowercase letters, numbers, hyphens, or underscores works: notes, journal, work-2026, …), import one from a git repo (a previously-exported Parachute vault on any HTTPS / SSH remote; PAT optional for private repos), or skip and create one later from the admin UI. You can add more vaults later either way; the name shows up in the URL for that vault's API + MCP endpoints (e.g. /vault/notes/mcp).
2. Expose. Hub auto-skips this step on Fly — the platform owns the public URL via *.fly.dev, so the three radio choices (localhost, tailnet, public-with-custom-domain) don't speak to your setup. You'll see a brief confirmation and move straight to Done.
3. Done. Two tiles: Open the admin UI (lands on /admin/vaults; from there you can navigate to /admin/modules to install Notes, Scribe, and any other modules) and Connect Claude Code (MCP) (the install command for the MCP wiring — see step 6).

What you should see. The done screen renders the claude mcp add command pre-filled with your hub's URL, vault name, and the auth header — the wizard auto-mints a fresh hub token scoped to your vault and drops it into the Authorization: Bearer flag for you. Copy-run it as-is. Step 6 walks the command and the fallback if you need to mint a token by hand.

5. Install modules from the admin UI

Why this step. The hub on its own is just the supervisor — useful for OAuth and module lifecycle, but not yet the thing you want to talk to. Modules are where the actual reading, writing, and capturing happens.

From the done screen's Open the admin UI tile (lands on /admin/vaults), navigate to Modules — that's /admin/modules. You'll see Vault, Surface, and Scribe listed as available (three modules, not four — Notes ships bundled inside Surface). Click Install next to each one you want. Install takes about a minute per module — the hub runs bun install against the package and persists it under /parachute/modules/node_modules/, then spawns it as a child process and mounts its routes under /vault, /surface, /scribe. Installing Surface auto-bootstraps the Notes UI as its first hosted surface.

What you should see. Each installed module switches to a Running badge with its mounted path. Notes is reachable at <your-hub>/surface/notes/ (the legacy <your-hub>/notes/ URL still resolves via hub's redirect), vault's REST API at <your-hub>/vault/default, scribe at <your-hub>/scribe.

6. Connect Claude Code

Why this step. The vault is running and reachable, but no client is wired to it yet. Claude Code talks MCP over HTTP — one command registers the server in ~/.claude.json, then it picks it up on the next session.

The simplest path: copy the claude mcp add command straight off the wizard's done screen and run it. The wizard already auto-minted a hub token scoped to your vault and pre-filled the Authorization: Bearer header — the command is complete as shown. On a hosted deploy there's no local browser for the OAuth redirect, so you attach the token explicitly here (unlike a laptop install, where Claude Code completes the browser sign-in for you):

If you closed the done screen or want to mint your own token, either source works — both return a hub JWT (not a legacy pvt_ string; vault no longer issues those):

• Admin UI → Tokens — go to /admin/tokens, create a token scoped to your vault (default vault:default:write — replace default with your vault name if you chose a different one), and copy the JWT it returns.
• On the hub host: parachute auth mint-token --scope vault:default:write (replace default with your vault name if you chose a different one) prints a JWT to stdout (default 90-day lifetime).

Then re-run claude mcp add with that JWT in the header flag (or edit the entry in ~/.claude.json directly). Start a new Claude Code session in any project, run /mcp — parachute-default should appear with its nine tools resolved. Memory now persists across every session, backed by your Fly-hosted hub.

What you should see. parachute-default in /mcp's list with status connected. Asking Claude to write a note succeeds and the note appears in the Notes UI on <your-hub>/surface/notes/ immediately.

Custom domain (optional)

Why this step. The *.fly.dev subdomain works forever, but most people want their own domain — both for memorability and because the OAuth tokens the hub mints are bound to a canonical origin you'd rather control.

1. Attach the domain. fly certs add your-domain.example.com --app your-app-name. Fly returns the DNS records you need to add.
2. Add DNS records. Point a CNAME (or A + AAAA records, per Fly's instructions) from your subdomain to your app. Wait for propagation (usually under a minute).
3. Fly auto-provisions TLS. Once DNS resolves, Fly fetches a Let's Encrypt certificate. fly certs show your-domain.example.com --app your-app-name reports the status.
4. Pin the issuer. fly secrets set PARACHUTE_HUB_ORIGIN=https://your-domain.example.com --app your-app-name. The machine restarts; tokens minted after this are bound to the new origin.

Cost

• Machine: ~$3.19/month for shared-cpu-1x 512MB always-on in iad. Other regions are slightly more (sjc ~$3.89, lax ~$4.05). Pricing varies; see Fly's pricing for current rates.
• Volume: $0.15/GB/month. The 1GB default volume is $0.15/month. Vault databases are tiny; typical single-operator usage stays well under 1GB through the first year.
• Snapshots: automatic daily snapshots, 5-day retention, free up to 10GB allowance — effectively free for single-operator usage.
• Custom domain: free, assuming you already own the domain. TLS via Let's Encrypt is included.

Expected total: ~$3.34/month for hub + vault + app (with notes-ui auto-bootstrapped) + scribe running together in iad. Other regions add ~$0.50–$1/month.

Compare locally: the same stack on your own Mac or Linux box is free, but you give up the always-on URL and the "works from my phone, anywhere" property. The Fly path is the trade.

Compare to Render: Fly's ~$3.34 vs Render's $7 flat — about half. Render's GUI ops are nicer if you don't want a CLI; Fly's volume snapshots are portable if you ever want to move your data elsewhere.

Limitations

• One machine shares 512MB of RAM. Fly shared-cpu-1x 512MB is enough for hub + vault + app + scribe at typical sub-1000-note usage. If you hit the ceiling — large vaults, heavy transcription workloads — scale up with fly scale memory 1024 --app your-app-name (triggers a machine restart, ~30s downtime). Or split a module out to its own Fly app later.
• Single-region by default. The default fly.toml pins one region. Multi-region Parachute would need volume replication, which Fly doesn't do natively for single-writer SQLite workloads. If iad has a bad day, your hub is down until they fix it. Same constraint as Render's regional disks; not a Fly-specific limit.
• CLI install required. Unlike Render's one-button deploy, you need flyctl on your machine. The deploy script installs it for you if missing, but the dependency is real.
• Module installs take a minute. Each "Install" click runs a real bun install on the machine against the npm registry. First-time installs of vault or app take roughly a minute; redeploys re-use the cached volume.
• Redeploys are not zero-downtime. When you run fly deploy or push to the repo (if you've wired CI), the machine restarts. Expect ~30 seconds where the hub is unreachable. For a single-operator hub this is a non-issue; for teams it's worth knowing.
• Edge cold-start can briefly 502. Like every PaaS, Fly's edge proxy occasionally takes a few seconds to settle routes to a newly-started machine. Probes during that window may return 502. Once warm, the hub is stable.

What comes next

• Local install — the same stack on your own machine. Free, but sleeps when your laptop sleeps.
• Deploy to Render — the peer hosted path. GUI-first; pick the one that fits.
• v0.6 deploy architecture — the design note explaining why it's one container with hub-as-supervisor.
• Fly migration design note — the strategic context for why we added Fly as a peer to Render.
• parachute-hub issues — deploy questions, bugs, friction. We read all of them.