Code is a thinking medium.

The problemMixed teams can’t think in code together.

A marketer has an idea for the buying-guide page. A PM wants to sketch a new checkout flow. A founder wants to show investors what the v2 dashboard could look like. The fastest path from idea to “here’s a working draft” runs straight through the codebase — but the codebase is locked behind “clone the repo, install Postgres, configure your env, get the API keys, restore a backup, install Redis, hope it works.”

So instead the team mocks it up in Figma, writes it up in a doc, argues about it in Slack, and an engineer eventually builds something that’s close to the intent but not quite. Two weeks have passed. The idea got smaller along the way.

boring closes that gap. One command opens an isolated container with the real app, real-shape data, and Claude already at the keyboard. The marketer prompts the change. The page renders. The screenshot goes in the deck. The engineer reviews it Monday.

How it worksThe same six steps for any stack.

Whether the repo is a Shopify theme, a Django + React app, a Next.js + Mongo project, a FastAPI service, or a polyglot data pipeline, the loop is the same. Every field in the profile maps to a docker-compose or devcontainer primitive — boring is glue, not magic.

1. Install once. brew install devcontainer jq yq, install Orbstack or Docker Desktop, install boring via the curl one-liner. boring doctor tells you what’s missing — including which optional secret-resolver CLIs (op, vault, security, aws) your profile happens to need, written in language that means something to a non-engineer.
2. Drop a profile into the repo. .boring/profile.yaml declares: the base image (a curated preset, or your own stack.dockerfile:), any sidecars (services: — postgres, redis, mongo, kafka, anything compose accepts), any host mounts, any forwarded ports, any env, any secret URIs, any first-run setup commands, any guardrails. Use as few fields as your project needs. Reviewable in a PR.
3. Open it. boring open . parses + validates the profile, resolves secret:// URIs from your existing store in memory, generates .devcontainer/docker-compose.yml (with healthcheck-aware depends_on auto-wired between sidecars and the dev service), and brings everything up via the standard devcontainer CLI.
4. Setup runs once, automatically. Any setup: commands (migrations, dependency installs, seeding, build steps — anything your project needs on first up) run after sidecars report healthy. boring writes a success marker; if it’s missing post-up, boring re-runs the chain. Belt-and-suspenders against the “hook half-failed and nobody noticed” case.
5. Think in code with Claude in the loop. Your forwarded ports are live on localhost. Edit in VS Code (attached via the standard Dev Containers extension — nothing boring-specific). Claude inside the container is project-scoped: this project’s MCP servers, this project’s memory, this profile’s tool allowlist. Prompt the change you want to see, take the screenshot, send it. Resolved secrets are visible to processes but never written to .env, the compose file, or disk.
6. Decide what becomes a PR. Sometimes the output is a mockup that goes in a deck. Sometimes it’s a wireframe attached to a Linear ticket. Sometimes it’s a real branch: commit from inside the container, gh pr create, your engineers review. The profile is the trust anchor — in-container agents can’t modify .boring/*, can’t disable the audit hooks, can’t push to forbidden branches.

Auto-clone via boring open <git-url> lands in v0.3. Headless boring run "<claude-prompt>" --profile X lands in v0.6 — fresh container per invocation, Claude prompts only (the shell-command equivalent is just devcontainer exec).

Why boringThe boring choices, finally.

Most “make dev easier” tools cheat by skipping the hard parts — isolation, real data, what the AI inside the box is actually allowed to do — and you find out at the worst possible moment. boring is built around three priorities, in this order:

Under the hoodDesign calls worth explaining.

Every interesting decision is recorded as an ARD in the repo. The seven below are the ones that drive the daily experience.

For your teamThe collaborative scratch pad.

boring is built for mixed teams — the engineer, the marketer, the manager, and the founder sitting at the same codebase, using code as a thinking medium together. The container is shared, the AI is shared, the conversation is shared. What anyone ships out of it is up to them.

Anatomy of a profile.boring/profile.yaml — every field, what it unlocks.

Use as many or as few fields as your project needs. Each field maps to a docker-compose or devcontainer primitive — no boring-specific magic, no “configuration as code” framework to learn. Empty fields are fine. Omit fields entirely when they don’t apply.

# .boring/profile.yaml
profile_version: "1"           # schema version; missing → warn, unknown → error w/ upgrade hint
name: your-app                 # slug; becomes the compose project name

# --- Base image: pick ONE of three paths ---
preset: django-node            # curated preset; v1.0 ships: python, node, node-postgres, django-node, shopify
preset_version:                 # override the preset's default language versions (build ARGs)
  python: "3.12"                #   default is 3.14; pin per-project as needed
  node: "20"                     #   default is 20; bump per-project as needed
# OR:
# stack:
#   dockerfile: ./Dockerfile.dev   # YOUR Dockerfile, anywhere in the repo
# OR:
#   base_image: node:20-bookworm-slim   # an existing registry image, no build

# --- Sidecars: any image compose accepts ---
services:
  - name: postgres                       # compose service name + DNS hostname on the network
    image: postgres:17
    env: { POSTGRES_DB: app, POSTGRES_PASSWORD: dev }
    volumes: [postgres-data:/var/lib/postgresql/data]
    healthcheck: { test: ["CMD", "pg_isready", "-U", "postgres"], interval: 5s }
  - name: redis
    image: redis:7
  # … or mongo, mysql, kafka, clickhouse, minio — anything in a registry.
  # dev.depends_on is auto-wired: service_healthy when there's a healthcheck,
  # service_started otherwise.

volumes: [postgres-data]                  # top-level named volumes (referenced by services[].volumes)

# --- Mounts: share host dirs into the container ---
mounts:
  - ~/.config/gh:/home/dev/.config/gh         # for browser-OAuth tools (gh, shopify, gcloud, firebase, …)
  - ~/.aws:/home/dev/.aws:ro                  # :ro is supported

# --- Ports: simple integer list, forwarded host↔container ---
forward_ports: [8000, 5173]

# --- Env: literal values + secret URIs side by side ---
env:
  DJANGO_DEBUG: "True"                     # literal — written to compose's environment block

  # Secrets — resolved at container start, never written to disk.
  # SEVEN URI schemes; pick whichever matches your team's secret store.
  OPENROUTER_API_KEY: secret://op://Personal/OpenRouter/api-key   # 1Password
  STRIPE_KEY:         secret://keychain:com.stripe/test-key      # macOS Keychain / Linux libsecret
  VAULT_TOKEN:        secret://vault://secret/data/app/token       # HashiCorp Vault
  AWS_API_KEY:        secret://aws-sm:prod/app/api-key             # AWS Secrets Manager
  DBX_SECRET:         secret://dbx-vault:app-secret                # dbx vault
  FROM_HOST_ENV:      secret://env:MY_LOCAL_VAR                    # host env (CI escape hatch)
  FROM_FILE:          secret://file:/run/secrets/api-key           # local file (Docker secrets, k8s mounts)

# --- Setup: any shell-command list, runs once after first up ---
setup:
  - uv sync --dev
  - uv run python manage.py migrate
  - (cd frontend && npm install)              # subshelled — cd does NOT bleed into the next command
  - ./scripts/seed.sh

# --- Guardrails (schema parsed today; codegen ships in v0.3) ---
guardrails:
  forbid_branches: [main, production]
  forbid_commands: ["gh pr merge", "kubectl apply"]
  allowed_claude_tools: [read, edit, grep, bash]

# --- Audit (v0.3): tiered visibility for events vs. prompt content ---
audit:
  events: shared                            # guardrail violations, restores, egress blocks: team-wide, always logged
  prompts: per_user                          # engineers see their own prompts only; set "shared" to opt into team learning

# --- Restore (v0.5): real-shape data into sidecars, sanitized via dbx ---
restore:                                    # piped through dbx restore --transform, never on disk unsanitized
  - source: dbx://prod/app-postgres         #   backup to draw from
    target: postgres                          #   which sidecar service to restore into
    transform: ./scripts/sanitize.sql          #   the dbx --transform script that strips PII
    when: on_first_up                          #   on_first_up | on_request | never

data_sensitivity: internal                # internal | sanitized | public (gates ephemeral volumes; v0.5)

egress:                                    # declarative today; enforcement ships v0.4 with iptables-in-container
  allow: [api.anthropic.com, github.com, registry.npmjs.org, openrouter.ai]

claude:
  mcp: []                                  # project-scoped MCP servers (Linear, Sentry, etc.)

Two real profiles in the wild today: a production Shopify theme (host bind-mounts for the CLI’s OAuth tokens, no setup hooks, no sidecars) and a Django + React + Postgres app (preset + secret URIs + setup chain + sidecar). Both use the same schema above. ARDs for every design call.

CapabilitiesWhat boring does, what ships when.

Honest tags. today = working in the current dev build (v0.2 shipped; v0.3 in progress). v0.3 through v1.0 = on the roadmap below, scheduled, not yet shipping.

RoadmapWhere it goes from here.

Total calendar from here to v1.0: ~3-4 months. v0.3 lands on early team members for phased feedback; v1.0 is the public release. Full release plan + thesis evolution: ARD-0008.

Get startedToday — the early-adopter path.

The repo is private during v0 development — access is by invite while Tom personally helps the first team members install. The v0.3 slice flips the repo public and ships the one-line curl installer. brew deferred to v1.x.

# prerequisites: docker (Orbstack on Mac), then:
$ brew install devcontainer jq yq    # yq must be the mikefarah Go variant
$ git clone git@github.com:steig/boring.git ~/code/boring
$ export PATH="$HOME/code/boring:$PATH"
$ boring doctor

# in any boring-enabled repo (one with .boring/profile.yaml):
$ boring open .

# coming in v0.3 — the one-line install:
# $ curl -fsSL https://boring.steig.io/install.sh | bash

Want access, or to chat about whether boring fits your team? Reach tom@steig.io. Architecture and decisions are all in docs/ards/ — designed in the open, recorded as ARDs, evolved as we learn.