Cmux Backend

cmux Backend

Use this skill for backend TypeScript, Cloud VM, provider, database, auth, rate-limit, retry, timeout, or telemetry work.

Core rules

• Default backend TypeScript to Effect under web/app/api/**, web/services/**, and backend scripts that touch providers, databases, auth, rate limits, retries, timeouts, or telemetry.
• Keep Next route handlers thin: parse the request, run one Effect program at the boundary, map typed errors to HTTP responses, and treat unexpected defects separately.
• Use plain TypeScript only for trivial data shapes, constants, config files, frontend React code, or small glue where Effect would add ceremony without improving failure handling.
• Cloud VM backend logic must stay in Vercel route handlers and Effect services backed by Postgres.
• Do not reintroduce Rivet or a raw actor protocol for Cloud VM unless a later architecture doc explicitly changes the control plane.
• Production and staging Cloud VM Postgres use the Vercel Marketplace AWS Aurora PostgreSQL OIDC/RDS IAM path.
• Runtime env names are CMUX_DB_DRIVER=aws-rds-iam, AWS_ROLE_ARN, AWS_REGION, PGHOST, PGPORT, PGUSER, and PGDATABASE.
• Run production/staging migrations with bun db:migrate:aws-rds-iam; never run Drizzle migrations from Vercel build or route startup.
• Local development keeps using the CMUX_PORT-derived Docker Postgres path from bun dev.
• Cloud VM create pricing gates should use Stack Auth team payment items when enabled.
• Postgres remains the source of truth for VM lifecycle, active VM limits, idempotency, and usage events.

Secrets

Cloud VM build, test, and local dev scripts use provider secrets from ~/.secrets/cmux.env.

• E2B_API_KEY
• FREESTYLE_API_KEY
• R2 upload vars used by web/scripts/build-cloud-vm-images.ts when creating Freestyle snapshots

Load them with:

set -a
source ~/.secrets/cmux.env
set +a

~/.secrets/cmuxterm-dev.env is for local Stack/web env and does not contain the provider build keys. bun dev sources ~/.secrets/cmux.env first when present, then ~/.secrets/cmuxterm-dev.env so cmuxterm-specific Stack settings override broader cmux secrets. The web dev loader still accepts the legacy ~/.secret/cmuxterm.env and ~/.secrets/cmuxterm.env paths while machines migrate.

Detailed references

• Read references/effect-boundaries.md when shaping route handlers, services, typed errors, retries, or dependency injection.
• Read references/cloud-vm-control-plane.md when touching VM lifecycle, migrations, Postgres, provider idempotency, or pricing gates.

Cloud VM Control Plane

This reference expands the Cloud VM rules for lifecycle, persistence, migrations, and provider coordination.

Source of truth

Postgres is the source of truth for:

• VM lifecycle state
• active VM limits
• idempotency records
• usage events
• provider identifiers
• team/account ownership

Provider state is observed and reconciled, not treated as the canonical application state. If provider state and database state disagree, write code that makes the reconciliation explicit.

Vercel and Effect boundary

Cloud VM backend logic lives in Vercel route handlers and Effect services. Route handlers should not become a raw actor protocol or long-running in-memory control plane. The durable state belongs in Postgres, and request-time workflows should be idempotent.

Do not reintroduce Rivet or a raw actor protocol unless a later architecture document explicitly changes this control plane.

Migrations

Production and staging migrations use:

bun db:migrate:aws-rds-iam

Never run Drizzle migrations from Vercel build or route startup. Build/startup migrations make deploy behavior non-deterministic and couple app availability to schema mutation.

Local development keeps using the CMUX_PORT-derived Docker Postgres path from bun dev.

AWS RDS IAM runtime

Production and staging Cloud VM Postgres should use the Vercel Marketplace AWS Aurora PostgreSQL OIDC/RDS IAM path with these runtime env names:

• CMUX_DB_DRIVER=aws-rds-iam
• AWS_ROLE_ARN
• AWS_REGION
• PGHOST
• PGPORT
• PGUSER
• PGDATABASE

Avoid inventing parallel env names for the same settings. Every new name creates another migration and deploy surface.

Pricing and active limits

Cloud VM create pricing gates should use Stack Auth team payment items when enabled. Active limits and usage events should be persisted, not inferred from transient process memory.

When changing create/start flows, verify:

• idempotency prevents duplicate provider creates
• team ownership is checked before provider allocation
• active VM limits are enforced before expensive provider work
• usage events are written exactly once for the lifecycle moment they represent
• failed provider calls leave a recoverable database state

Effect Boundaries

This reference expands the backend TypeScript rules for route handlers, services, and scripts.

Route handler shape

Route handlers should be shallow adapters. They should parse request input, construct or select the required Effect program, run it once at the boundary, and translate domain errors to HTTP responses. Keep workflow sequencing, retries, provider calls, and database updates outside the handler body.

A good handler answers these questions quickly:

• What input does the route accept?
• Which Effect program performs the workflow?
• Which typed errors map to expected HTTP statuses?
• Which failures are unexpected defects?

Avoid route handlers that interleave parsing, database writes, provider calls, and response construction. That shape makes retries and idempotency hard to audit.

Service shape

Use Effect services when a workflow crosses an external boundary or has meaningful failure semantics:

• provider APIs
• database reads or writes
• auth and team lookup
• payment or quota checks
• retries and timeout policy
• telemetry and usage recording
• idempotency claims

Model expected failures as typed domain errors. Prefer names that describe the business failure, not the transport layer. For example, VmLimitExceeded, ProviderCapacityUnavailable, or IdempotencyConflict is more useful to callers than a raw FetchError.

Dependency shape

Make service dependencies explicit. Do not hide important runtime dependencies behind globals when an Effect service can receive them as layer requirements.

Good dependencies are concrete capabilities:

• database client
• provider client
• auth/team service
• clock or timeout policy
• telemetry sink
• idempotency repository

Bad dependencies are broad ambient containers or untyped option bags that force every workflow to rediscover what it actually needs.

Plain TypeScript carve-out

Plain TypeScript is fine for data-only code:

• constants
• schema declarations
• config objects
• frontend components
• pure formatting helpers
• tiny route glue with no external effects

The point is not to use Effect everywhere. The point is to use it where explicit failure, dependency, retry, and cancellation semantics reduce real ambiguity.

Error mapping

Expected domain errors should become clear HTTP responses. Unexpected defects should not be disguised as expected user errors.

When adding a new route, check that:

• invalid input maps to 400 or the existing validation status
• auth and entitlement failures map to the existing auth/payment statuses
• active-limit or quota failures are explicit
• provider unavailability is distinguishable from a defect
• idempotency conflicts return a deterministic response

If a caller needs to retry, the response should make that practical.