# Dev Instance

Run the current worktree as a production-shaped local dev instance with web, Slack, or...

- Repository: https://github.com/yc-software/qm (15597 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add yc-software/qm --skill dev-instance -g -a claude-code -y`
Codex: `npx skills add yc-software/qm --skill dev-instance -g -a codex -y`
Cursor: `npx skills add yc-software/qm --skill dev-instance -g -a cursor -y`
Gemini CLI: `npx skills add yc-software/qm --skill dev-instance -g -a gemini-cli -y`

## Description

Run the current worktree as a production-shaped local dev instance with web, Slack, or both, on a real LLM + Postgres. Each developer uses their own set of Slack apps from their own machine's pool store, so many worktrees (yours and a teammate's) can run reachable at once without colliding. Use when asked to /dev-instance, "spin this up so I can QA it in Slack", or "let me test your branch end to end".

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

# dev-instance

`dev-instance` runs the current worktree with the surfaces needed for the task.
Choose web for browser/admin work, Slack for bot work, and both only for cross-surface QA. It is the way to QA a
branch end to end: real LLM turns, a real sandbox, a real local Postgres (empty by
default; opt in to prod data), and the real Slack/web/admin surfaces.

Use the repo-root launcher (a thin wrapper over the TypeScript CLI in `scripts/dev/`;
every command accepts `--json` for machine-readable output):

```bash
bash scripts/dev-instance.sh up --surface web
bash scripts/dev-instance.sh up --surface slack
bash scripts/dev-instance.sh up --surface both
bash scripts/dev-instance.sh status
bash scripts/dev-instance.sh down
bash scripts/dev-instance.sh doctor
bash scripts/dev-instance.sh canary
bash scripts/dev-instance.sh restart [child]
bash scripts/dev-instance.sh logs [child] [-f]
```

`npm run dev-instance`, `npm run dev-instance:status`, `npm run dev-instance:down`, and
`npm run dev-instance:doctor` are equivalent. The Codex-visible skill copy lives at
`.codex/skills/dev-instance/SKILL.md`; keep the two skill descriptions equivalent.

New instances default to web only. `npm run dev-instance:web`,
`npm run dev-instance:slack`, and `npm run dev-instance:both` select a surface explicitly.
Bare `up` preserves the mode of an existing instance. Explicitly selecting a different
surface tears down and boots the worktree again, claiming the appropriate slot.
`--no-slack` (and `DEV_INSTANCE_NO_SLACK=1`) remain aliases for web only.

## What `up` Starts

`up --surface slack` and `up --surface both` claim one free Slack app slot from **this machine's** pool store (see "Slack reach"
below), then spawns a **per-slot supervisor daemon** that owns the production-shaped stack:

- core API + workers in every mode
- Slack Socket Mode plugin in `slack` and `both`
- web UI, admin, and portal front door in `web` and `both`

The rest: https://github.com/yc-software/qm/blob/HEAD/.codex/skills/dev-instance/SKILL.md