molecule-ai/docs
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #121 from Molecule-AI/fix/docs-fly-to-aws-railway-migration

Browse Source 
docs: update Fly Machines references to AWS EC2 + Railway (Apr 2026 migration)
This commit is contained in:
Hongming Wang 2026-05-04 05:11:22 -07:00 committed by GitHub
commit c76a284c9a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 45 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
content/docs/architecture.mdx
View File

@ -296,7 +296,9 @@ docker compose up
### SaaS
Hosted at `moleculesai.app` with per-tenant isolation. Each tenant gets a dedicated Fly Machine running the tenant image. The `MOLECULE_ORG_ID` env var gates API access -- every non-allowlisted request must carry a matching `X-Molecule-Org-Id` header or gets a 404. When unset, the guard is a passthrough so self-hosted and dev environments are unaffected.
Hosted at `moleculesai.app` with per-tenant isolation. Each tenant gets a dedicated AWS EC2 instance running the tenant image, provisioned by the control plane (`api.moleculesai.app`, hosted on Railway). The `MOLECULE_ORG_ID` env var gates API access -- every non-allowlisted request must carry a matching `X-Molecule-Org-Id` header or gets a 404. When unset, the guard is a passthrough so self-hosted and dev environments are unaffected.
> **Migration note (Apr 2026):** SaaS infrastructure was migrated from Fly Machines to AWS EC2 (workspaces) + Railway (control plane). See the [`molecule-controlplane` README "Migration history"](https://github.com/Molecule-AI/molecule-controlplane#migration-history) for the canonical record.
### Tenant Image

34
content/docs/self-hosting/admin-token.mdx
View File

@ -30,7 +30,28 @@ platform.
## Setting ADMIN_TOKEN in production
### Fly.io (recommended for self-hosted)
The platform reads `ADMIN_TOKEN` from the process environment, so any
production-grade host with a secrets store works. Pick the path that
matches your deployment target.
> **Note (Apr 2026):** The Molecule AI SaaS itself runs on AWS EC2
> (workspaces) + Railway (control plane). Self-hosters can use any host
> with secret-injection (Railway, Fly.io, AWS, GCP, bare-metal) — the
> examples below are illustrative, not prescriptive. See the
> [`molecule-controlplane` README "Migration history"](https://github.com/Molecule-AI/molecule-controlplane#migration-history)
> for the canonical SaaS infrastructure record.
### Railway
In the Railway dashboard, go to your service → Variables and add
`ADMIN_TOKEN`, then redeploy. Or via CLI:
```bash
railway variables --set ADMIN_TOKEN="your-generated-token"
railway up
```
### Fly.io
```bash
fly secrets set ADMIN_TOKEN="your-generated-token"
@ -92,10 +113,13 @@ payload with a `count` field, the token is working.
To rotate without downtime:
1. **Deploy** the new token: `fly secrets set ADMIN_TOKEN="new-token" && fly deploy`
2. **Verify** the new token works (see above)
3. **Remove** the old token: `fly secrets unset OLD_TOKEN_NAME` (Fly does not
persist old secret values after unset)
1. **Deploy** the new token via your host's secrets store, e.g.
`railway variables --set ADMIN_TOKEN="new-token" && railway up`
or `fly secrets set ADMIN_TOKEN="new-token" && fly deploy`.
2. **Verify** the new token works (see above).
3. **Remove** the old token from the secrets store. Most managed hosts
(Railway, Fly.io, AWS Secrets Manager) do not persist old secret
values after unset.
## Related

13
content/docs/tutorials/fly-machines-provisioner.md
View File

@ -1,8 +1,19 @@
---
title: "Provisioning Workspaces on Fly Machines (CONTAINER_BACKEND=flyio)"
title: "Provisioning Workspaces on Fly Machines (CONTAINER_BACKEND=flyio) — DEPRECATED"
---
# Provisioning Workspaces on Fly Machines (CONTAINER_BACKEND=flyio)
> **DEPRECATED — historical reference only.** As of April 2026, the SaaS
> control plane and tenant/workspace fleets migrated off Fly Machines to
> **AWS EC2 (workspaces) + Railway (control plane)**. The current
> production provisioner lives at
> [`molecule-controlplane/internal/provisioner/ec2.go`](https://github.com/Molecule-AI/molecule-controlplane/blob/main/internal/provisioner/ec2.go).
> The Fly provisioner code (`fly.go`, `internal/flyapi/`) remains in the
> tree as legacy awaiting cleanup but is no longer the production path.
> See the [`molecule-controlplane` README "Migration history"](https://github.com/Molecule-AI/molecule-controlplane#migration-history)
> for the canonical record. This page is preserved as the original PR
> #501 lineage record; do not follow it for new self-hosted deployments.
Molecule AI can provision agent workspaces on [Fly Machines](https://fly.io/docs/machines/) instead of local Docker containers. When `CONTAINER_BACKEND=flyio` is set, every `POST /workspaces` creates a Fly Machine and boots the workspace agent inside it — with tier-based resource limits, env-var injection, and A2A registration handled automatically. The platform manages the workspace (lifecycle, auth, routing); Fly manages the machine it runs on.
> **Scope note (PR #501):** Workspace images must already be published to GHCR before provisioning. The `delete` and `restart` platform endpoints are not yet fully wired to the Fly provisioner — use `flyctl machine stop/destroy` for teardown until a follow-up PR lands.

2
content/docs/tutorials/saas-federation.md
View File

@ -226,7 +226,7 @@ This terminates all EC2 instances, drops the Neon branch, and removes the org re
|---|---|---|
| Database | Neon branch-per-tenant | Tenant's branch, operator has no direct access |
| Compute | EC2 in tenant's VPC | Control plane provisions, operator manages SG rules |
| Credentials | No Fly/API tokens on tenant | All cloud credentials held by control plane |
| Credentials | No AWS/cloud API tokens on tenant | All cloud credentials held by control plane |
| API access | Org-scoped API keys | Tenant manages their own keys; operator has CP-level override |
| Network | Security group: port 443 from platform only | Control plane manages; tenant can't modify |