Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What 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-settings

2Manually: put the files in place

.claude/rules/manage-instances.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for DevOps and infrastructure →

From the same set113

The whole set →
shell-and-workflows The shell-and-workflows rule documents Docker commands for the project and explains where to run frontend and backend tests. Use it when managing services or checking a change. CX Codex +1 ★ 1,216repo stars js-request-idle-callback js-request-idle-callback — a rule that moves analytics, state saving and prefetching into idle browser time so the interface stops stuttering on every click. CX Codex +1 ★ 1,216repo stars pr-comment-resolver pr-comment-resolver inspects unresolved pull request reviews, applies necessary code updates, and drafts replies for reviewers. Ideal for clearing PR feedback without manual issue hunting. CX Codex ★ 1,216repo stars list-performance-item-types list-performance-item-types is a Claude Code rule for lists with mixed layouts. It guides the agent to assign item types and keep unlike cells in separate recycling pools. CX Codex +1 ★ 1,216repo stars test-audit The test-audit skill reviews new and changed tests, and helps spot duplicates or low-value checks. Use it when adding tests or auditing an existing suite. CX Codex +1 ★ 1,216repo stars webmcp-gen webmcp-gen turns a page workflow into a WebMCP tool and checks that the tool matches the behavior of the existing UI. CX Codex +1 ★ 1,216repo stars start-environment start-environment teaches the assistant how to spin up local development containers via dev docker up, wait for healthchecks, and inspect ports. CX Codex +1 ★ 1,216repo stars service-architecture The service-architecture rule maps Polar’s shared Docker infrastructure and per-worktree app stacks. Use it to understand service addresses, container dependencies, and network boundaries. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open