The Project Registry

The registry is Foundry's source of truth for which projects exist on your machine and what automation applies to each one. Without a populated registry, the daemon starts successfully but skips all project-specific work.

Where the Registry Lives

By default: ~/.foundry/registry.json

Override the path with the environment variable:

export FOUNDRY_REGISTRY_PATH=/path/to/my-registry.json

The daemon reads the registry on startup. If the file is missing it logs a warning and continues with an empty registry (no projects will be processed).

Single Source of Truth

The running daemon holds an in-memory copy of the registry in a read-write lock. Online foundry registry list, show, add, edit, and remove commands all go through the daemon's typed gRPC API so reads and writes observe the same daemon-owned state. Direct file access is reserved for explicit recovery with --offline. Without --offline, an unreachable daemon is an error and the client-side registry file is left untouched. Online registry commands also do not create FOUNDRY_REGISTRY_PATH when it does not already exist. The one exception is foundry registry init, which is always an explicit offline-only recovery command:

foundry registry add --name my-tool …             # daemon-authoritative
foundry --offline registry add --name my-tool …   # direct registry.json recovery

Registry Format (v2)

{
  "version": 2,
  "projects": [
    {
      "name": "my-tool",
      "path": "/Users/alice/projects/my-tool",
      "stack": "rust",
      "agent": "claude",
      "repo": "alice/my-tool",
      "branch": "main",
      "skip": false,
      "actions": {
        "iterate": true,
        "maintain": true,
        "push": true,
        "audit": true,
        "release": false
      },
      "install": {
        "command": "cargo install --path ."
      }
    }
  ]
}

Top-level fields

ProjectEntry fields

Accepted-risk advisories

Record an accepted advisory in the repository's .supply-chain-allow.json (see Supply-chain scan). Every entry has a written reason and an expiry, and it lives in git. The post-push auditor, the scan_requested scan and the nightly supply-chain scan all read it. An active entry accepts the finding; a lapsed one resurfaces it. An entry matches when it names any identifier the scanner reports for the advisory (for example PYSEC, CVE or GHSA for the same pip-audit finding).

The older registry field audit_exceptions still works, with the same alias matching, but it has no expiry and no registry edit flag:

{
  "name": "my-service",
  "audit_exceptions": ["CVE-2026-45829"],
  "notes": "CVE-2026-45829: chromadb vector store path is not exposed; accepted risk 2026-06-27."
}

Matching is case-insensitive. Each accepted finding is logged at info level and named in the audit's result line (accepted: PYSEC-2026-311 (allowlist)), so suppression is never silent. Remove an entry once the upstream advisory is patched.

Stack values

The stack field tells Foundry which audit tool to use and how to run stack-specific commands.

Supply-chain auto-fix support differs by stack: Rust, TypeScript, and Python have a full update and a targeted pin; Swift has the full update (swift package update) only; Kotlin, Elixir, and C++ report no_fixer. Dependency updates in the maintain workflow are agent-driven and do not depend on the stack.

ActionFlags

The actions object controls which steps run during a maintenance run. All flags default to false when the actions key is absent.

InstallConfig

The install field configures how the project is reinstalled locally after automation completes. Exactly one variant is used per entry:

Command — runs an arbitrary shell command in the project directory:

"install": { "command": "cargo install --path ." }

Brew — installs via a Homebrew formula:

"install": { "brew": "my-formula" }

Homebrew installs run on macOS only. On any other host, Install Locally skips the step with "install via brew not supported on " and never starts brew; the maintenance summary shows the skip and its reason. Clear the config on that host with foundry registry edit <name> --clear-install, or give it a command install that works there.

An install command that fails, or cannot be started at all, is recorded as a failed local_install_completed event with the reason in details, and the maintenance summary lists it under Local Installs.

Skill install

The installs_skill field tells Foundry to run a skill-install command after a successful local install. A failed skill install is a warning. It does not fail the install.

Use the object form when the binary name is not the project name (for example, project hone-cli with binary hone). Set the field from the CLI with --installs-skill true, --installs-skill false, or --installs-skill "hone init --global --force".

Minimal Project Entry

Only the six required fields are needed. All optional fields default to safe values (no actions enabled, no install step, not skipped):

{
  "version": 2,
  "projects": [
    {
      "name": "minimal-project",
      "path": "/Users/alice/projects/minimal-project",
      "stack": "rust",
      "agent": "claude",
      "repo": "alice/minimal-project",
      "branch": "main"
    }
  ]
}

Excluding a Project Temporarily

Set skip to a string reason to pause automation without removing the entry:

{
  "name": "on-hold",
  "path": "/Users/alice/projects/on-hold",
  "stack": "typescript",
  "agent": "claude",
  "repo": "alice/on-hold",
  "branch": "main",
  "skip": "Waiting for CI to stabilise"
}

The value of skip is the human-readable reason displayed in foundry registry show. Absent, null, false, or an empty string all mean "not skipped". For backwards compatibility, true is treated as the reason string "skipped".

The Validate Project block silently acknowledges skipped projects (emits project_validation_completed with status: "skipped") so the engine trace remains complete.

Managing the Registry with the CLI

Rather than editing registry.json by hand, use the foundry registry subcommands. All commands respect FOUNDRY_REGISTRY_PATH for non-default locations.

foundry registry list, show, add, edit, and remove are daemon-authoritative in normal online use: they talk to foundryd over gRPC and operate on the daemon-owned in-memory registry state. Direct filesystem access is reserved for explicit offline recovery with --offline. Without --offline, an unreachable daemon is an error and leaves the client-side registry file untouched. If FOUNDRY_REGISTRY_PATH is absent, the online path still leaves it absent. If daemon persistence fails during an online add/edit/remove, the RPC returns a stable INTERNAL error and leaves the daemon-owned registry unchanged.

# Create an empty registry during offline recovery
foundry --offline registry init

# List all projects from the daemon-owned registry
foundry registry list

# Inspect one project from the daemon-owned registry
foundry registry show my-tool

# Add a new project through the daemon
foundry registry add \
  --name my-tool \
  --path /Users/alice/projects/my-tool \
  --stack rust \
  --agent claude \
  --repo alice/my-tool \
  --iterate --maintain --push \
  --install-command "cargo install --path ." \
  --notes "Main CLI toolchain"

# Offline recovery: mutate the file directly while the daemon is stopped
foundry --offline registry add \
  --name my-tool \
  --path /Users/alice/projects/my-tool \
  --stack rust \
  --agent claude \
  --repo alice/my-tool

# Edit an existing project
foundry registry edit my-tool --timeout-secs 3600

# Let maintenance take major upgrades (each one becomes its own task)
foundry registry edit my-tool --update-policy major

# Remove the install configuration
foundry registry edit my-tool --clear-install

# Run a skill install after the local install (true | false | "<command>")
foundry registry edit hone-cli --installs-skill "hone init --global --force"

# Skip a project temporarily
foundry registry edit my-tool --skip "Waiting for CI to stabilise"

# Clear a skip (resume automation)
foundry registry edit my-tool --skip ""

# Remove a project
foundry registry remove my-tool

See CLI Commands — foundry registry for the full option reference.

Multiple Projects

A single registry file can declare any number of projects. They are processed concurrently during a maintenance run (up to max_concurrent at a time, which defaults to the number of active projects unless the orchestrator is configured otherwise):

{
  "version": 2,
  "projects": [
    {
      "name": "api-server",
      "path": "/Users/alice/projects/api-server",
      "stack": "rust",
      "agent": "claude",
      "repo": "alice/api-server",
      "branch": "main",
      "actions": { "iterate": true, "maintain": true, "push": true }
    },
    {
      "name": "frontend",
      "path": "/Users/alice/projects/frontend",
      "stack": "typescript",
      "agent": "claude",
      "repo": "alice/frontend",
      "branch": "main",
      "actions": { "maintain": true, "push": true }
    }
  ]
}