molecule-core/docs/blog/2026-04-17-deploy-anywhere/index.md

title	date	slug	description	tags
Deploy AI Agents on Fly.io — or Any Cloud — with One Config Change	2026-04-17	deploy-anywhere	Molecule AI supports fly.io agent deployment and control-plane provisioning. Switch backends with one env var — no agent code changes required.	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 (Fly Machines provisioner) and PR #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:

CONTAINER_BACKEND=flyio
FLY_API_TOKEN=<your-fly-deploy-token>
FLY_WORKSPACE_APP=<your-fly-app-name>

# 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

See also: Give Your AI Agent a Real Browser: MCP + Chrome DevTools — wire Chrome DevTools Protocol into your Molecule AI workspace via MCP for production-grade browser automation.

---

PR #501 (Fly Machines provisioner) and PR #503 (control plane provisioner) are both merged to main. Molecule AI is open source — contributions welcome.