Deploy Hermes Agent to Fly.io with a single command.
Interactive CLI wizard that provisions, configures, and manages a Hermes instance on Fly.io.
- Deploy wizard -- guided setup that provisions your app, volume, VM, and secrets
- Status -- check app health, machine state, region, and URL at a glance
- Logs -- stream or tail live application logs
- Doctor -- run diagnostic checks to verify connectivity, auth, and app health
- Destroy -- clean teardown of app, volumes, and local config
- Messaging -- optional Telegram and Discord notification setup
curl -fsSL "https://raw.githubusercontent.com/alexfazio/hermes-fly/main/scripts/install.sh" | bashThis installs the latest published hermes-fly release by default. The
installer prefers packaged release assets and falls back to a source build only
when an older tag does not provide one. Fresh installs default to a user-local
launcher in ~/.local/bin plus an OS-specific install home (~/.local/share
on Linux via XDG defaults, ~/Library/Application Support on macOS). Existing
installs are upgraded in place so current /usr/local users do not get moved
silently. To pin a specific release:
HERMES_FLY_VERSION=vX.Y.Z curl -fsSL "https://raw.githubusercontent.com/alexfazio/hermes-fly/main/scripts/install.sh" | bashInstall channels are also supported via HERMES_FLY_CHANNEL:
stable(default): latest release tagpreview: currently followsstableuntil a dedicated preview stream is publishededge: installs from movingmain(non-reproducible)
HERMES_FLY_CHANNEL=edge curl -fsSL "https://raw.githubusercontent.com/alexfazio/hermes-fly/main/scripts/install.sh" | bashOr clone and run directly:
git clone https://github.com/alexfazio/hermes-fly.git
cd hermes-fly
./hermes-fly deployhermes-fly deployThe wizard walks you through:
- Platform and prerequisite checks
- Fly.io authentication
- App name, region, VM size, and volume configuration
- API key and model selection
- Optional messaging setup (Telegram / Discord)
- Build, deploy, and health verification
| Command | Description |
|---|---|
hermes-fly deploy |
Launch the interactive deploy wizard |
hermes-fly status |
Show app status, machine state, and URL |
hermes-fly logs |
Stream live application logs |
hermes-fly doctor |
Run diagnostic checks on deployment |
hermes-fly destroy |
Tear down app, volumes, and local config |
Fly.io charges are usage-based. Typical monthly costs:
| VM Size | Mem | VM | +1 GB | +5 GB | +10 GB |
|---|---|---|---|---|---|
| shared-cpu-1x | 256 MB | ~$2.02 | $2.17 | $2.77 | $3.52 |
| shared-cpu-2x | 512 MB | ~$4.04 | $4.19 | $4.79 | $5.54 |
| performance-1x | 2 GB | ~$32.19 | $32.34 | $32.94 | $33.69 |
Volume storage: $0.15/GB/month. See Fly.io Pricing and Fly.io Calculator for current rates.
- flyctl -- the Fly.io CLI.
- macOS or Linux -- Windows is not supported.
- A Fly.io account -- sign up free at fly.io.
- curl and git -- standard on most systems.
If hermes-fly is not already on your PATH, the installer prints the exact
export PATH=... command to add the launcher directory for your shell.
Secrets (API keys, bot tokens) are stored via
fly secrets set and never written to disk. They
are injected as environment variables at runtime.
No secrets appear in fly.toml, Dockerfile, or
local config.
The prerequisite auto-install feature is tested across diverse environments:
- 57 edge case tests covering platform detection, PATH safety, and signal handling
- 370+ total tests with zero regressions and 100% pass rate
- Explicit edge case validation for:
- Platform detection (unsupported platforms, fallback behavior)
- PATH modifications in restricted environments
- Signal handling (SIGTERM, SIGINT, SIGKILL cleanup)
- Binary & malformed output handling
- CI/CD integration (--no-auto-install flag, CI=true bypass)
- Security hardening (command injection prevention)
- Boundary conditions (long paths, special characters, empty inputs)
- Permission errors (sudo failures, write denied)
See docs/EDGE_CASE_HANDLING.md for details on edge case handling and test coverage.
hermes-fly dispatches all commands through Commander.js (TypeScript runtime via node dist/cli.js).
No migration environment flags are required.
Run this check to enforce DDD layer boundaries in src/contexts during migration.
npm run arch:ddd-boundariesnpm run test:domain-primitivesThese tests validate domain invariants with zero IO mocks.
npm run parity:checkCaptures deterministic command snapshots and compares them to the committed parity baseline.
See the docs/ directory for detailed guides:
- Getting Started -- step-by-step deployment walkthrough
- Messaging Setup -- Telegram and Discord configuration
- Troubleshooting -- common issues and fixes
- Release Operations -- stable promotion gates, drift checks, and rollback playbook
