Reference

Configuration

Configuration reference is assembled from JSON Schema. The left column explains fields and constraints; the right column is generated from schema defaults and examples.

overplane.yaml

Per-project configuration for Overplane, stored as overplane.yaml at the project root. The file is created by overplane init from the defaults in this schema, is intended to be checked into version control, and is strictly validated (unknown keys are errors) every time Overplane reads it. All paths inside the file are relative to the directory that contains overplane.yaml.

schema_version

Version of the overplane.yaml format. Only 1 is accepted; Overplane refuses files written for a newer or unknown revision rather than guessing at their meaning, and never rewrites the file to migrate it.

schema_version example

schema_version: 1

project

Identity of the project that owns this file. These values appear in command output and generated artifacts.

Required

Globally unique, identifier-friendly project name. overplane init derives it from the project directory name, lowercased with unsupported characters replaced by hyphens. Must start with a lowercase letter or digit and may contain lowercase letters, digits, dots, underscores, and hyphens.

pattern ^[a-z0-9][a-z0-9._-]*$ min length 1 max length 100

Optional

Optional one-line summary of the project, used for display only.

max length 500

dirs

Overplane-managed directories, given as paths relative to the project root (the directory containing overplane.yaml). Absolute paths and paths that escape the root with .. are rejected.

Required

Directory holding the project's spec documents: numbered Markdown files with YAML frontmatter. This is the durable record of your project's intent and belongs in version control.

min length 1

Directory for disposable, machine-local working state. It is never committed: overplane init adds it to .gitignore and creates it on demand. Deleting it is always safe.

min length 1

Directory where overplane build writes its final generated output. This is the default destination for -o/--output.

min length 1

Directory for the Intermediate Representation (IR) files produced during the build pipeline.

min length 1

sandbox

The project's sandbox container: the environment in which AI coding agents run. overplane sandbox build builds a local image from this section, labeled with the project name; nothing is pushed anywhere. The section is optional, and a file without it behaves as if the defaults shown here were written out.

Required

Container engine that builds and runs the sandbox. docker requires Docker with Buildx/BuildKit 0.13 or newer; podman requires Podman 5.x / Buildah 1.32 or newer with reproducible-build support.

one of "docker", "podman"

Image the sandbox is built from, for example debian:bookworm-slim or alpine:3. Its OS family must match the selected setup_recipe.

min length 1 max length 200

Built-in provisioning recipe that prepares the base image: OS updates, a broad developer toolchain, project packages, and a container user mirroring your host identity. It also selects which extra_packages family applies: debian uses apt, alpine uses apk. See the Agent Environment reference for the full contents.

one of "debian", "alpine"

AI coding agents to install into the sandbox, in install order. Each entry names a recipe from Overplane's embedded registry and an optional version. An empty list builds a toolchain-only sandbox with no agents.

Registry name of the agent recipe: codex (OpenAI Codex), claude-code (Anthropic Claude Code), gemini-cli (Google Gemini CLI), or opencode (OpenCode).

one of "codex", "claude-code", "gemini-cli", "opencode"

Registry name of the feature recipe: playwright (Playwright CLI + headless Chromium on debian, distro chromium on alpine).

one of "playwright"

Optional

Additional OS packages to install, keyed by package family. Only the family matching the selected setup_recipe is used. Extras install in their own image layer, so editing this list never invalidates the cached toolchain layers.

no extra fields

apt package names installed with the debian setup recipe, for example graphicsmagick.

apk package names installed with the alpine setup recipe.

Agent CLI version to install: an npm dist-tag (latest, preview) or an exact version (2.1.3). Aliases resolve from the npm registry on each setup run; the resolved version is recorded in the build hash.

pattern ^[a-z0-9][a-z0-9._-]*$ min length 1 max length 64

Optional sandbox capabilities to install into the final image (for example browser testing). Each entry names a recipe from Overplane's embedded registry. An empty list skips all feature layers.

Additional host environment variables to copy into the sandbox, beyond the API keys each configured agent recipe already receives (for example OPENAI_API_KEY for codex). Values listed here reach every container started by overplane sandbox run, so add secrets deliberately.

sandbox example

sandbox:
  runtime: docker
  base_image: "debian:bookworm-slim"
  setup_recipe: debian
  extra_packages:
    debian: []
    alpine: [""]
  agent_recipes:
    -
      name: codex
      version: latest
    -
      name: claude-code
      version: latest
    -
      name: gemini-cli
      version: latest
    -
      name: opencode
      version: latest
  feature_recipes:
    -
      name: playwright
  env_passthrough: []

agents

Named agent configurations that specs and commands can select by name (for example image-gen or cc-fable-sonnet) instead of repeating backend and model settings. One entry must be named default; it is used when no agent is specified.

Required

Unique name for this configuration. The entry named default is required and is used when no agent is selected.

pattern ^[a-z0-9][a-z0-9._-]*$ min length 1 max length 100

Agent backend for this configuration: codex, claude-code, gemini-cli, or opencode. It must also appear in sandbox.agent_recipes so its CLI is installed in the sandbox image.

one of "codex", "claude-code", "gemini-cli", "opencode"

Optional

Model id passed to the backend when this configuration is selected. Empty uses the backend's default model.

agents example

agents:
  -
    name: default
    backend: claude-code
    model: ""
  -
    name: codex
    backend: codex
    model: ""
  -
    name: opencode
    backend: opencode
    model: openrouter/z-ai/glm-5.2