Configuration reference

Summary of Station layout, key config files, and how they relate to Safehouses and installs. For YAML samples, field tables, and merge troubleshooting detail, see upstream configuration.md.

Overview

• Home office — In upstream docs this means the GitHub repository (source of standard packages and documentation), not a directory on your machine.
• Station — Local hub: config, catalog, published packages (default ~/.atp_station, or STATION_PATH).
• Safehouse — Per-project .atp_safehouse with manifest.yaml and local config.

Naming convention

• Directories: underscores (e.g. ~/.atp_station, .atp_safehouse).
• Config files: dash-separated with atp- prefix (e.g. atp-config.yaml, atp-catalog.yaml, atp-package.yaml).

Station layout (typical)

~/.atp_station/
  atp-config.yaml
  atp-catalog.yaml
  atp-safehouse-list.yaml
  standard_packages/
    <name>/
      atp-package.yaml
      package.tar.gz
  user_packages/
    <name>/
      atp-package.yaml
      package.tar.gz

STATION_PATH overrides the default ~/.atp_station root.

atp-safehouse-list.yaml

The Station keeps atp-safehouse-list.yaml (under the same root as atp-config.yaml) listing Safehouse paths that have registered with this Station—used for cross-project operations (for example Station-level removal with --exfiltrate). See upstream docs/configuration.md for the safehouse_paths shape.

atp-config.yaml

Resolved at ${STATION_PATH}/atp-config.yaml or ~/.atp_station/atp-config.yaml when STATION_PATH is unset.

Contains at least a configuration.version and agent-paths: for each agent id (cursor, claude, gemini, codex, kiro, …), paths such as home_path, project_path, and per-type folders (rule, prompts, skills, hooks, commands, etc.). Agents may define only home_path where project-scoped trees are not used—see upstream samples (codex, claude).

Optional YAML keys (commented in upstream templates) include:

• npm-registry-base-url — HTTPS origin for the npm registry API when the CLI checks for newer releases (atp --latest and background notices). Omit to use the public registry; value must be https:.
• standard-catalog — URL for a default curated package source.

atp-catalog.yaml

packages must be a mapping with both standard and user keys; each is a YAML list (use [] when empty). Each list item must be a mapping with at least name, plus optional version, description, and location (e.g. file://); location may be omitted when not applicable. Bare package name strings or a flat packages: [ … ] list are invalid and are treated as no packages.

The same name in user overrides standard for installs and atp catalog list. There is no separate global or per-project catalog file—only this Station file.

The file may omit the outer catalog: key and list packages at the top level. Paths like standard_packages-path / user_packages-path point at package trees under the Station.

Safehouse manifest

Under .atp_safehouse/:

• manifest.yaml — which catalog packages are installed, versions, install source, binary scope, and the STATION_PATH from which they were installed.
• Local config — used when resolving installs; may record agent, ATP version, and related metadata.

atp safehouse init refuses to create .atp_safehouse when the resolved project root is the user’s home directory (for example ~/.git / ~/.vscode markers under $HOME, or SAFEHOUSE_PROJECT_PATH pointing at $HOME). Set ATP_ALLOW_HOME_SAFEHOUSE=1 exactly to override; any other value keeps the guard (same behaviour as Safehouse and agent).

Standard vs user packages

Standard packages are typically sourced from the upstream project or another curated catalog entry. User packages are entries you add under packages.user and publish into user_packages/—ATP manages install/remove for those through the same Station catalog.

Package manifest (atp-package.yaml) — modern layout

For Multi (type: Multi or multi in examples):

• Root fields: name, type, version, optional developer, license, copyright, etc.
• parts is required with at least one part. Each part: type, mandatory usage, optional components, bundles.

Root-level usage, components, and bundles are optional for Multi because those values normally live on parts. Legacy compatibility keeps those root fields optional on disk even when using Multi.

Each bundle object has path and exec-filter (glob for executables relative to package root).

Legacy single-type packages use a root type other than Multi (for example Rule) with root usage / components / bundles as required by validation—do not mix a populated parts array with a non-Multi root type.

Authoring vs install: changing parts (add/remove part, component, or bundle) is an authoring-time workflow with atp package … in the package directory. After catalog publish and install, only whole-package removal applies (atp remove safehouse / atp remove station); ATP does not uninstall individual parts from a project.

Part type values and validation rules align with upstream package developer documentation: Feature 2 — Package developer support.

Extended field tables and a full Multi YAML example: upstream docs/configuration.md (section Extended atp-package.yaml layout).

Install merges (MCP / hooks)

When atp install runs with --project (typical default) or --station, Mcp and Hook parts may merge into agent-specific JSON or config files. Paths depend on the Safehouse agent and Station agent-paths—for example Cursor .cursor/mcp.json and .cursor/hooks.json, Gemini .gemini/settings.json (MCP and hooks), Codex .codex/config.toml (MCP) and .codex/hooks.json (hooks).

If an existing MCP server or hook identity matches (name or dedupe key) but content differs, install fails until --force-config or --skip-config. --verbose, or DEBUG containing atp, may print an extra one-line JSON payload on stderr for those failures.

See Install, list, and remove and upstream Feature 5 — Installer providers for known agents (merge policy and troubleshooting).

---

← Manual index · Site home