# Cmux Backend

Backend TypeScript and Cloud VM development rules for cmux.

- Repository: https://github.com/manaflow-ai/cmux (28635 stars)
- Category: Media
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add manaflow-ai/cmux --skill cmux-backend -g -a claude-code -y`
Codex: `npx skills add manaflow-ai/cmux --skill cmux-backend -g -a codex -y`
Cursor: `npx skills add manaflow-ai/cmux --skill cmux-backend -g -a cursor -y`
Gemini CLI: `npx skills add manaflow-ai/cmux --skill cmux-backend -g -a gemini-cli -y`

## Description

Backend TypeScript and Cloud VM development rules for cmux. Use when editing web/app/api, web/services, backend scripts, Cloud VM lifecycle, provider integrations, Postgres, Stack Auth pricing gates, migrations, or provider image build scripts.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# cmux Backend

## Core rules

- Default backend TypeScript to Effect under `web/app/api/**`, `web/services/**`, and backend scripts touching 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, treat unexpected defects separately.
- Plain TypeScript is for trivial data shapes, constants, config files, frontend React, and small glue where Effect would add ceremony without improving failure handling.
- Cloud VM backend logic stays in Vercel route handlers and Effect services backed by Postgres. Do not reintroduce Rivet or a raw actor protocol unless a later architecture doc explicitly changes the control plane.
- Postgres is the source of truth for VM lifecycle, active VM limits, idempotency, and usage events.
- Production and staging Cloud VM Postgres use PlanetScale PostgreSQL database `cmux-prod` in organization `cmux`. The runtime reads `DATABASE_URL` with `CMUX_DB_DRIVER=url`; migration jobs use the protected `DATABASE_URL` secret. AWS credentials are not database credentials.
- Run production/staging migrations with `bun run cloud-vm:migrate -- staging` followed by `-- production`; never from Vercel build or route startup. Local dev keeps the `CMUX_PORT`-derived Docker Postgres path from `bun dev`.
- Cloud VM create pricing gates use Stack Auth team payment items when enabled.

## Secrets

Cloud VM build, test, and local dev scripts read provider secrets from `~/.secrets/cmux.env`: `FREESTYLE_API_KEY` and the R2 upload vars `web/scripts/build-cloud-vm-images.ts` needs when creating Freestyle snapshots.

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

The rest: https://github.com/manaflow-ai/cmux/blob/HEAD/skills/cmux-backend/SKILL.md