Deploy and build

You've got a helipod serve deployment running (see Self-hosting). Now you want to ship a code change to it without rebuilding the container or restarting the process.

There are two ways to do that, plus a third path if you'd rather skip containers entirely:

• helipod deploy pushes local helipod/ changes to an already-running serve and hot-swaps them in live, with no restart.
• helipod build compiles your whole app into one self-contained executable, for when you'd rather ship a binary than a Docker image.
• The provisioning targets (cloudflare, docker, railway, fly, aws), a different helipod deploy mode entirely. They provision infrastructure, they don't hot-swap.

This page covers all three. If you already know what you're looking for, jump straight there:

• helipod deploy: live hot-swap
• The six deploy targets
• Deploying from CI (GitHub Actions)
• helipod build: one self-contained binary
• Choosing between deploy, build, and Docker, the comparison table, if you're not sure which of the three fits

helipod deploy: live hot-swap onto a running server

helipod deploy transpiles your local helipod/ functions and additive schema changes, then pushes them to a running helipod serve deployment. The server validates everything and applies it atomically: it keeps serving requests the whole time, and a rejected deploy never leaves it half-updated.

helipod serve --dir helipod --allow-deploy
# or, equivalently:
HELIPOD_ALLOW_DEPLOY=1 helipod serve --dir helipod

HELIPOD_ADMIN_KEY=your-strong-secret helipod deploy --url https://myapp.example

✓ deployed via serve (production) — rev 4b3187d88b93 (7 functions, 2 changed)
  https://myapp.example

Responses and status codes

Additive-only schema: destructive changes are rejected, not migrated

There are no data migrations in Helipod today. diffSchema compares your pushed schema against the server's live one, field by field and table by table.

Allowed (accepted, swap proceeds):

• Adding a brand-new table.
• Adding a new optional field to an existing table.

Rejected (409, server stays on the previous version):

• Removing or renaming a table.
• Changing a table's internal table number. This shouldn't happen under normal use: table numbers are stable across a deploy specifically so this check never fires on a legitimate change.
• Removing a field from an existing table.
• Changing a field's type, including what looks like a safe widening, like string to a union that includes string, or any to string. The diff can't verify a "widening" is actually sound against every existing row (an any column may hold values that aren't valid strings), so v1 takes the conservative position: any field-type change is rejected. Over-rejecting only fails a deploy. It can never corrupt data, which is the property this gate exists to protect.
• Turning an existing optional field required.
• Adding a new required field to an existing table. Existing rows don't have it, so make it optional instead, and backfill via a mutation if you need every row populated.

Any of these come back as deploy failed: <reason> describing exactly which table and field failed and why:

✗ deploy failed: field "notes.priority" changed type string→number (destructive)

The component set is fixed at boot

Components composed via helipod.config.ts (@helipod/scheduler, @helipod/workflow, and any others) are whatever was declared when serve booted. helipod deploy can push new functions and additive schema against that fixed component set, but it can't add or remove a component on a live server. Changing the component list in helipod.config.ts requires restarting the process, or redeploying the container.

Worked example

# 1. Start a deploy-enabled server (once)
HELIPOD_ADMIN_KEY=prod-secret helipod serve --dir helipod --allow-deploy &

# 2. Make a change locally: add a new query, add an optional field to schema.ts
#    (edit helipod/notes.ts, helipod/schema.ts)

# 3. Push it live (run `helipod codegen` first if schema/functions changed)
HELIPOD_ADMIN_KEY=prod-secret helipod deploy --url http://localhost:3000
# ✓ deployed via serve (production) — rev 4b3187d88b93 (8 functions, 2 changed)
#   http://localhost:3000

# 4. The new function is callable immediately, no restart:
curl -X POST http://localhost:3000/api/run \
  -H 'content-type: application/json' \
  -d '{"path":"notes:add","args":{"box":"b1","text":"hello"}}'

Any WebSocket client subscribed to a query touching the notes table before step 3 sees the write from step 4 pushed to it reactively. The deploy in between didn't drop or reset the subscription.

Going deeper: what a deploy actually does

The six deploy targets

helipod deploy --url <url> (documented above) is shorthand for one specific target: --target serve, the default. The general form is --target <name> --env <name> (plus --dry-run and --check), and the other five targets provision infrastructure instead of hot-swapping an already-running process. Target settings and credentials can live in the deploy block of helipod.config.ts (see Configuration).

Provider CLIs are never bundled into helipod; each target shells out to the one you already have installed, and fails preflight with a clear install hint if it's missing. Only the serve target uses the additive-schema gate described above. The provisioning targets ship a whole new build/image, so there's nothing to gate: the platform's own rollout replaces the process.

Deploying from CI (GitHub Actions)

CI is just another caller of the same command: the workflow below runs the identical helipod deploy a human runs locally, with credentials coming from repository secrets.

name: deploy
on:
  pull_request:
  push: { branches: [main] }
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run test
      # PRs: verify committed codegen is current; exits before any target preflight, so
      # it needs no secrets. Add --dry-run to also validate target preflight/packaging
      # (the serve target's preflight then wants HELIPOD_DEPLOY_URL + HELIPOD_ADMIN_KEY).
      - if: github.event_name == 'pull_request'
        run: bunx helipod deploy --check
      # main: the real deploy (serve target).
      - if: github.ref == 'refs/heads/main'
        run: bunx helipod deploy
        env:
          HELIPOD_DEPLOY_URL: ${{ secrets.HELIPOD_DEPLOY_URL }}
          HELIPOD_ADMIN_KEY: ${{ secrets.HELIPOD_ADMIN_KEY }}

Three properties make this workflow safe to copy:

• It never hangs. helipod deploy derives its interactive mode from stdin.isTTY and the CI environment variable (GitHub Actions sets CI=true on every runner), so a missing credential fails fast with an actionable message and a non-zero exit instead of prompting.
• --check gates codegen drift. It exits 1 if helipod/_generated/ doesn't match a fresh codegen run, which matters doubly for the serve target since a serve deploy never regenerates it. --dry-run additionally runs the target's preflight and package steps without pushing.
• Exit codes are real. A rejected schema change, a failed --check, or a provider CLI error all exit 1 and fail the job like any other CI step.

For a provisioning target, swap the deploy line and secrets: bunx helipod deploy --target cloudflare with CLOUDFLARE_API_TOKEN (plus a npm i -D wrangler install step), --target railway with RAILWAY_TOKEN, --target fly with FLY_API_TOKEN, and so on per the table above. Tokens always come from CI secrets; the provider CLIs' interactive login flows have no place in a headless runner.

helipod build: one self-contained binary

helipod build compiles your entire app, the Bun runtime, the Helipod engine, bun:sqlite, your helipod/ functions and schema, and any composed components, into a single executable via bun build --compile. At deployment time you need nothing but the binary and a data directory: no bun/node install, no node_modules, no helipod/ source tree.

helipod build

helipod build --outfile ./dist/my-backend

✓ built ./helipod-server (58MB)

HELIPOD_ADMIN_KEY=your-strong-secret ./helipod-server --port 3000 --hostname 0.0.0.0 --data-dir ./data

{"ready":true,"port":3000,"url":"http://0.0.0.0:3000"}

Other limitations

• Single instance. SQLite requires exclusive file access, so it's one binary process per data directory (unless you pass --database-url to point it at Postgres, in which case the usual single-writer advisory-lock rules from Postgres apply instead).
• No helipod init scaffolder. You bring your own helipod/ directory. helipod build doesn't generate one.

Worked example: fixture app with a component, then cross-compiled

This mirrors the shipped end-to-end test:

helipod build --dir helipod --outfile ./helipod-server --no-dashboard
# ✓ built ./helipod-server (58MB)

HELIPOD_ADMIN_KEY=e2e ./helipod-server --port 3599 --hostname 127.0.0.1 --data-dir ./data
# {"ready":true,"port":3599,"url":"http://127.0.0.1:3599"}

curl -X POST http://127.0.0.1:3599/api/run \
  -H 'content-type: application/json' \
  -d '{"path":"notes:add","args":{"box":"a","text":"compiled"}}'
# {"value":null,"committed":true,...}

# Cross-compile the same app for a Linux server:
helipod build --dir helipod --target linux-x64 --outfile ./dist/server-linux --no-dashboard
# ✓ built ./dist/server-linux (95MB)

Going deeper: how the build works

Cross-compilation

helipod build --target linux-x64 --outfile ./dist/server-linux

helipod build --target linux-arm64 --outfile ./dist/server-linux-arm64

helipod build --target darwin-arm64 --outfile ./dist/server-macos

helipod build --target darwin-x64 --outfile ./dist/server-macos-x64

helipod build --target windows-x64 --outfile ./dist/server-windows.exe

A windows-x64 target automatically appends .exe to --outfile if you didn't already include it.

Deployment patterns for the binary

HELIPOD_ADMIN_KEY=your-strong-secret ./helipod-server --hostname 0.0.0.0 --port 8080 --data-dir /var/lib/helipod

FROM gcr.io/distroless/base-debian12
COPY dist/helipod-server /helipod-server
EXPOSE 3000
VOLUME /data
ENTRYPOINT ["/helipod-server", "--hostname", "0.0.0.0", "--data-dir", "/data"]

helipod build --target linux-x64 --outfile ./dist/helipod-server
docker build -f Dockerfile.binary -t my-app-binary .
docker run -p 3000:3000 -e HELIPOD_ADMIN_KEY=your-strong-secret -v helipod-data:/data my-app-binary

[Unit]
Description=Helipod Server
After=network.target

[Service]
Type=simple
Environment=HELIPOD_ADMIN_KEY=your-strong-secret
ExecStart=/opt/helipod/helipod-server --data-dir /var/lib/helipod --hostname 0.0.0.0
Restart=on-failure
User=helipod

[Install]
WantedBy=multi-user.target

Choosing between deploy, build, and Docker self-hosting

In practice these aren't mutually exclusive: you can run helipod serve --allow-deploy in a container and use helipod deploy against it for day-to-day shipping, falling back to rebuilding the image only when you need to change the composed component set.

Related

• Self-hosting with Docker: the serve deployment helipod deploy pushes onto, and the bind-mounted-image alternative to the standalone binary.
• Postgres: --database-url/HELIPOD_DATABASE_URL, accepted by both serve and the compiled binary.
• Cloudflare: helipod deploy --target cloudflare, and the general --target/--env provisioning model.
• Local dev: helipod dev, the hot-reload loop this page's deploy and build both build on.