diff --git a/docs/blog/2026-04-17-deploy-anywhere/index.md b/docs/blog/2026-04-17-deploy-anywhere/index.md new file mode 100644 index 00000000..f969055d --- /dev/null +++ b/docs/blog/2026-04-17-deploy-anywhere/index.md @@ -0,0 +1,108 @@ +--- +title: "Deploy AI Agents on Fly.io — or Any Cloud — with One Config Change" +date: 2026-04-17 +slug: deploy-anywhere +description: "Molecule AI supports fly.io agent deployment and control-plane provisioning. Switch backends with one env var — no agent code changes required." +tags: [platform, fly.io, deployment, infrastructure] +--- + +# Deploy AI Agents on Fly.io — or Any Cloud — with One Config Change + +Your infrastructure choice just got decoupled from your agent platform choice. Molecule AI now ships three production-ready workspace backends — `docker`, `flyio`, and `controlplane` — and switching between them takes a single environment variable. Your agent code, model choices, and workspace topology stay exactly the same. + +This post covers what shipped in [PR #501](https://github.com/Molecule-AI/molecule-core/pull/501) (Fly Machines provisioner) and [PR #503](https://github.com/Molecule-AI/molecule-core/pull/503) (control plane provisioner), and which backend fits your situation. + +## Before: One Deployment Model for Every Use Case + +Until this week, Molecule AI workspaces ran on one backend: Docker. That was the right default for self-hosters — no external dependencies, full control, works anywhere a Docker daemon runs. But it left two groups making a compromise they shouldn't have to: + +- **Indie developers and small teams** wanted Fly.io's economics: pay-per-use compute, fast cold starts, scale to zero when nobody's working. +- **SaaS builders** needed structural credential isolation. A Fly API token sitting in the tenant layer is one misconfiguration away from a security incident — not a policy problem, an architecture problem. + +Both groups were choosing between "use the platform" and "get the deployment model I need." That trade-off is gone. + +## Run AI Agents on Fly: The Indie Dev Path + +You're already on Fly. You have an account, a Fly app, and you're comfortable with Machines. You want Molecule AI workspaces to provision as Fly Machines — no separate Docker host, no idle infrastructure, just workspaces that appear when needed and disappear when they don't. + +Set three environment variables on your tenant platform instance: + +```bash +CONTAINER_BACKEND=flyio +FLY_API_TOKEN= +FLY_WORKSPACE_APP= + +# Optional — defaults to ord +FLY_REGION=ord +``` + +When a workspace is created, the Fly provisioner: + +1. Spins up a Fly Machine inside your `FLY_WORKSPACE_APP` +2. Injects workspace secrets and the platform registration URL as machine env vars +3. Selects the right GHCR image for the runtime (`hermes` → `ghcr.io/molecule-ai/workspace-hermes:latest`, and so on) +4. Applies tier-based resource limits — T2 at 512 MB / 1 vCPU, T3 at 2 GB / 2 vCPU, T4 at 4 GB / 4 vCPU +5. Issues a boot-time auth token so the workspace agent can register with the platform immediately + +Your workspaces run as first-class Fly Machines. When they're idle, Fly handles the scale-down. Your bill reflects actual usage, not reserved capacity. + +## Multi-Tenant Agent Provisioning Without Credential Sprawl + +You're building a SaaS product on top of Molecule AI. Each customer gets a Molecule workspace. The problem: if every tenant platform instance carries a `FLY_API_TOKEN`, you've distributed cloud credentials across your tenants — structurally. Policy controls help, but they don't remove the credential from the attack surface. + +`CONTAINER_BACKEND=controlplane` removes it entirely. + +``` +Canvas → Tenant Platform → Control Plane API → Fly Machines API +``` + +The tenant platform never holds a Fly token. It calls the Molecule control plane at `https://api.moleculesai.app` (overridable via `CP_PROVISION_URL` for staging environments), which holds Fly credentials and orchestrates workspace provisioning centrally. + +For standard SaaS deployments, you don't configure this manually — the platform auto-detects the right backend: + +- `MOLECULE_ORG_ID` set → SaaS tenant → **control plane provisioner activates automatically** +- `MOLECULE_ORG_ID` empty → self-hosted → **Docker provisioner, no change needed** + +The right backend is the default for your context. For most SaaS builders: set `MOLECULE_ORG_ID` at tenant launch, and credential isolation is structural from day one. + +## Self-Hosted vs Cloud AI Agents: Backend Comparison + +| Backend | `CONTAINER_BACKEND` | Best for | Who holds cloud credentials | +|---|---|---|---| +| **Docker** | *(empty / default)* | Self-hosted, local dev | No external credentials needed | +| **Fly Machines** | `flyio` | Indie devs / small teams on Fly | `FLY_API_TOKEN` lives on the tenant | +| **Control Plane** | `controlplane` | SaaS builders, multi-tenant products | Fly token held by control plane only — never on tenant | + +**Fly backend env vars** (for `CONTAINER_BACKEND=flyio`): + +| Variable | Required | Default | What it does | +|---|---|---|---| +| `CONTAINER_BACKEND` | Yes | — | Activates the Fly provisioner | +| `FLY_API_TOKEN` | Yes | — | Fly deploy token | +| `FLY_WORKSPACE_APP` | Yes | — | Fly app that hosts workspace machines | +| `FLY_REGION` | No | `ord` | Region for new machines | + +## Agent Orchestration in the Cloud: What Doesn't Change + +Switching backends changes where workspaces run, not how they work. From any agent runtime's perspective — Hermes, Letta, or whatever you're orchestrating — the workspace is the workspace. Unchanged across all three backends: + +- Agent registration and boot sequence +- Model routing and provider dispatch +- Workspace secrets injection +- The full platform API surface + +No changes to agent code, tool definitions, or orchestration logic. Swap `CONTAINER_BACKEND`, redeploy, done. + +## Multi-Agent Cloud Deployment: Choose Your Path + +- **Self-hosting?** Leave `CONTAINER_BACKEND` unset. Docker is the default — nothing to configure. +- **On Fly, small team?** Set `CONTAINER_BACKEND=flyio` with `FLY_API_TOKEN` and `FLY_WORKSPACE_APP`. Workspaces become Fly Machines in your own Fly account. +- **Building a SaaS product on Molecule AI?** Set `MOLECULE_ORG_ID` at tenant launch. The control plane provisioner activates automatically. No Fly credentials on the tenant, ever. + +**Pick your backend. Deploy your agents.** + +→ [Quickstart: choose your deployment backend](/docs/quickstart) + +--- + +*[PR #501](https://github.com/Molecule-AI/molecule-core/pull/501) (Fly Machines provisioner) and [PR #503](https://github.com/Molecule-AI/molecule-core/pull/503) (control plane provisioner) are both merged to `main`. Molecule AI is open source — contributions welcome.*