manage-instances — Claude Code rule: branch isolation in parallel stacks
manage-instances — a rule for running multiple isolated app stacks in separate worktrees, each with its own database, Redis index, and host ports.
Apache-2.0 ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat manage-instances does
The rule documents an instance model for the Polar project: each instance is an isolated app stack in a separate worktree, with dedicated host ports, database polar_dev_<N>, Redis index, and S3 buckets. Infrastructure (Postgres, Redis, MinIO) is shared across instances; only api, worker, and web containers are duplicated. Host ports follow a formula: base 8100 for api, 3100 for web, plus the instance number (instance 0 uses legacy ports 8000/3000).
The rule covers dev docker set-instance, dev docker list, and dev docker prune commands for pinning a worktree to a specific instance, listing registered instances, and reclaiming data from deleted branches. All commands accept an -i N flag to target an instance explicitly. Two or three instances run comfortably on a typical machine; each adds roughly 2 GB and its own build volumes.
What it helps with
- Run two project branches side by side, each in its own worktree
- Execute a long test suite in one instance while developing in another
- Compare before-and-after behaviour without tearing down the main stack
- Pin a worktree to a fixed port for integration with tooling
- Reclaim data from deleted worktrees via
dev docker prune
Example prompts for the agent
- Pin this worktree to instance 5 and bring up the stack
- Show all registered instances and their statuses
- Drop data for instances whose worktrees no longer exist
How to install manage-instances
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settings2Manually: put the files in place
.claude/rules/manage-instances.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/manage-instances.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/manage-instances.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/manage-instances.mdManually: put the files in place
.clinerules/manage-instances.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about manage-instances
How do I install the manage-instances rule in Claude Code?
Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install polar-skills@claude-settings. The rule will appear at .claude/rules/manage-instances.md.
What does the manage-instances rule do?
It documents an isolated instance model for the Polar project: each worktree gets its own app stack with dedicated ports, database, and Redis index, while infrastructure remains shared.
Which ports does instance 5 use?
API on port 8105, web on 3105 (formula: base 8100/3100 plus instance number). Database polar_dev_5, Redis index 5, buckets polar-s3-5 and polar-s3-public-5.
Source text
manage-instances.md · Apache-2.0
--- title: Managing Multiple Instances category: Operations tags: instances, parallel, isolation --- # Managing Multiple Instances ## What are instances? An instance is one worktree's isolated app stack (project `polar-app-<N>`). All instances share a single infra stack (`polar-shared`), but each gets: - Its own api/web **host ports** (offset per instance) - Its own database `polar_dev_<N>` on the shared postgres - Its own redis DB index `<N>` on the shared redis - Its own S3 buckets `polar-s3-<N>` / `polar-s3-public-<N>` on the shared minio So instances are cheap: only api/worker/web containers are duplicated, not the infra. ## Port mapping Only api and web publish host ports. Everything else is shared and reached by container name, so there is **no** per-instance `5532`/`6479`/`9100` — those ports don't exist in this model. | Service | Instance 0 | Instance 1 | Instance 2 | |---------|------------|------------|------------| | API (host) | 8000 | 8101 | 8102 | | Web (host) | 3000 | 3101 | 3102 | | DB (logical) | `polar_dev_0` | `polar_dev_1` | `polar_dev_2` | | Redis (DB index) | 0 | 1 | 2 | | S3 bucket | `polar-s3-0` | `polar-s3-1` | `polar-s3-2` | **Host-port formula (api/web only):** `Port = Base + Instance` (Base 8100 for api, 3100 for web), for instances 1–99. Instance 0 uses the legacy `8000`/`3000`. So instance 5 is api `8105` / web `3105`. Run `dev docker ports` in a worktree to print its resolved instance and URLs. ## Pinning and inspecting instances Auto-detection usually picks the right instance, but you can pin or inspect: ```bash dev docker set-instance 5 # pin this worktree to instance 5 (writes .env.docker + registry) dev docker clear-instance # back to auto-detect dev docker list # every registered instance: number, status, path dev docker prune # drop registry entries whose worktree is gone, and their data ``` Pinning makes ports deterministic, which is what you want when wiring a worktree into tooling like `.claude/launch.json`. ## Commands (explicit instance) Most commands auto-detect, but `-i N` targets one explicitly: ```bash dev docker up -i 1 -d # start instance 1 dev docker ps -i 1 # status dev docker logs -i 1 api # logs dev docker down -i 1 # stop dev docker shell -i 1 api # shell ``` ## Use cases - **Branch A vs branch B** side by side, each in its own worktree. - **Run a long test suite** in one instance while developing in another. - **Before/after comparisons** without tearing down your main stack. ## Resource notes Each app stack adds ~2 GB and its own build/cache volumes; the shared infra is paid once. Two or three instances is comfortable on a typical machine. Use `dev docker prune` to reclaim data from worktrees you've deleted.
© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings