# cmux-backend

Rules for cmux backend TypeScript and Cloud VM work, covering Effect, Postgres, migrations, provider integrations, and auth pricing gates.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4700 installs · ★ 28491
- Author: manaflow-ai
- License: GPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/manaflow-ai/cmux/tree/HEAD/skills/cmux-backend/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/cmux-backend

## What it does

cmux-backend guides backend changes in cmux. It sets when to use Effect in `web/app/api/**`, `web/services/**`, and scripts that handle providers, databases, auth, limits, retries, timeouts, or telemetry. Next.js route handlers should parse the request, run one Effect program, and turn typed failures into HTTP responses.

The skill also covers Cloud VM lifecycle state, active-VM limits, idempotency, usage events, and Stack Auth payment checks. It refers to `DATABASE_URL`, `CMUX_DB_DRIVER=url`, the migration command `bun run cloud-vm:migrate -- staging` followed by `-- production`, and provider secrets from `~/.secrets/cmux.env`. Run migrations as a separate operation, not from route startup or a Vercel build. Local development keeps the Docker Postgres path used by `bun dev`.

## Requirements
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-backend -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cmux-backend/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cmux-backend/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-backend -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cmux-backend/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-backend -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cmux-backend/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install manaflow-ai/cmux cmux-backend
```

2. **Manually: put the files in place**
- File: `.github/skills/cmux-backend/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-backend -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/manaflow-ai/cmux --path skills/cmux-backend
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cmux-backend/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-backend -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/manaflow-ai/cmux/tree/HEAD/skills/cmux-backend/SKILL.md

## When to use it
- separate Next.js route parsing from Effect logic
- model Cloud VM lifecycle state in Postgres
- run staging and production migrations
- apply Stack Auth pricing gates to VM creation
- load provider secrets for Cloud VM image builds

## Example prompts
- Apply `cmux-backend` to a new route under `web/app/api` and move its error handling into Effect.
- Review the Cloud VM image build script and load provider secrets from `~/.secrets/cmux.env`, including `FREESTYLE_API_KEY`.
- Prepare the Cloud VM database migration and run it for `staging`, then for `production`.

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [manaflow-ai/cmux](https://affpapa.org/en/nevibecode/by/manaflow-ai/cmux.md) — 24 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md