start-environment — Claude Code rule: what it does, how to install
start-environment teaches the assistant how to spin up local development containers via dev docker up, wait for healthchecks, and inspect ports.
Apache-2.0 ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat start-environment does
The rule documents operations around dev docker up, which spins up shared infra and app containers. Containers start detached by default. The guide directs the assistant to pass --wait so commands block until /healthz succeeds and the web service responds, avoiding broken scripts during slow startup phases.
Flags like -b and --pull are specified for image rebuilds. Pulling fresh base images resolves cached layer problems, such as stale interpreters after updating .python-version. It also details the initial setup sequence, covering uv sync, pnpm install, database bootstrapping, and database migrations.
Because host ports are allocated per instance, assuming default ports breaks multi-instance setups; the rule instructs the assistant to read endpoints via dev docker ports or dev docker ports --json.
What it helps with
- start local development containers and shared infra
- block execution until app healthchecks pass
- rebuild images and pull fresh bases after runtime updates
- discover assigned host ports for active worktree instances
Example prompts for the agent
- Start the local environment and wait until services are healthy
- Rebuild docker images with fresh base layers and start in the background
- Check which ports are assigned to this instance
How to install start-environment
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settings2Manually: put the files in place
.claude/rules/start-environment.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/start-environment.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/start-environment.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/start-environment.mdManually: put the files in place
.clinerules/start-environment.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about start-environment
How to install start-environment in Claude Code?
Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install polar-skills@claude-settings. You can also place the rule file directly at .claude/rules/start-environment.md.
What does start-environment do?
It provides instructions for Claude Code and Codex on managing local app stacks using dev docker up. It covers detached execution, log streaming, and troubleshooting stale base images.
Why should scripts use the --wait flag?
Containers return immediately in detached mode, but the app may still be running uv sync, pnpm install, or database migrations. The --wait flag guarantees that the API /healthz endpoint responds before subsequent steps run.
Source text
start-environment.md · Apache-2.0
--- title: Starting the Local Environment category: Operations tags: docker, start, development --- # Starting the Local Environment `dev docker up` starts shared infra (if it isn't already running) plus this worktree's app stack. It **defaults to detached** (`-d` is on by default), so plain `dev docker up` returns once containers are created. ## Basic commands **Start in background (the default):** ```bash dev docker up -d ``` **Start and block until app services are healthy:** ```bash dev docker up -d --wait ``` `--wait` returns only once api answers `/healthz` and web responds. Prefer it in scripts and tooling so "up finished" means "actually serving" rather than "the container was created" — on first boot the app keeps compiling and migrating for a while after the container starts. **Start in the foreground and stream logs:** ```bash dev docker up --no-detach ``` Shared infra still starts detached; only the app stack is attached, so Ctrl+C stops the app stack. **Start specific services:** ```bash dev docker up -d api # api (+ shared infra) dev docker up -d web # web (+ shared infra) dev docker up -d api worker # api and worker ``` ## Options | Flag | Description | | ----------------- | ---------------------------------------------------- | | `-d` / `--detach` | Detached / background (default) | | `--no-detach` | Foreground; stream app logs until you stop it | | `--wait` | Block until app services are healthy (detached only) | | `-b` / `--build` | Rebuild images before starting | | `--pull` | Refresh base images before building (see below) | | `--monitoring` | Include Prometheus and Grafana in shared infra | | `-i N` | Target instance N explicitly (usually auto-detected) | ## Rebuilding with fresh bases ```bash dev docker up -b --pull -d ``` `-b` rebuilds the images, and `--pull` refreshes the base images first. Use `--pull` after a `.python-version` bump or when a rebuild alone still boots the old interpreter — a cached `FROM` layer can otherwise pin you to a stale base. See troubleshooting for the "No interpreter found for Python X" symptom. ## First-time startup First run is slow because it does real work inside the containers: 1. Build the api/web images 2. `uv sync` (api/worker) and `pnpm install` (web) — several minutes 3. Bootstrap the per-instance DB and MinIO buckets 4. Run migrations and load seed data 5. Services become healthy `dev docker up -d --wait` is the cleanest way to wait this out. ## Finding the URLs Ports are per-instance, so don't assume 3000/8000. Ask: ```bash dev docker ports # human-readable dev docker ports --json # for tooling ``` For instance 0 the app is at http://localhost:3000 (web) and http://localhost:8000 (api, docs at `/docs`). MinIO exposes ports 9000 (API) and 9001 (console) on localhost; db and redis have no host port — reach them with `dev docker exec <service> ...`.
© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings