Configuration

Checkout Structure

A checkout is a local directory holding one agent. After apollo agent import or apollo agent create, it looks like this:

my-agent/
├── .apollorc                # org / project / agent / version_tag binding
├── bundle/
│   ├── src/                 # the editable program source — the only tree push reads
│   │   ├── program.yaml     # the program manifest
│   │   ├── vocabulary.yaml  # the agent's typed vocabulary
│   │   ├── situations.yaml  # situations the agent recognizes
│   │   ├── sources.yaml     # data & knowledge sources (hub: references)
│   │   ├── derivations.yaml # derived facts
│   │   ├── connections.yaml # external connection wiring
│   │   ├── capabilities/    # one directory per capability
│   │   └── policies/        # behavioral policies (e.g. global.yaml)
│   └── build/               # build & evaluation assets (scenarios, personas, …)
├── schemas/                 # authoring JSON Schemas for every program file
├── AGENTS.md                # authoring guide served by the agent's runtime
├── .claude/skills/          # authoring skill packs for Claude Code
└── .cursor/skills/          # authoring skill packs for Cursor

Path	Purpose
`.apollorc`	Binds the directory to an organization, project, agent, and version tag
`bundle/src/`	The program — typed YAML/Markdown files. Everything that must travel with the bundle is authored here; `push` reads only this tree
`bundle/build/`	Build and evaluation assets that ship as a build bundle
`schemas/`	JSON Schemas the CLI validates against, for editor autocomplete too
`AGENTS.md`	The authoring guide the agent’s runtime serves
`.claude/` · `.cursor/`	Coding-agent skill packs installed on import/create (skip with `--no-skills` on pull)

Open the agent folder as your coding-tool project root so the skill packs are discovered. The skill packs are a snapshot from import time — apollo pull refreshes them along with the schemas and AGENTS.md (skip with --no-skills / --no-schemas).

The `.apollorc` Binding

.apollorc

{
  "config_version": 1,
  "org_id": "…",
  "project_id": "…",
  "agent_id": "…",
  "version_tag": "v7.2",
  "runtime_version": "0.8.11"
}

Context is positional: the nearest .apollorc walking up from your current directory selects the agent. Commands run inside a checkout use its binding for organization, project, agent, and version.

Don’t edit .apollorc manually — apollo agent use / import, apollo project use, apollo version use, and apollo runtime use maintain it, and apollo push updates the tag on every push.

User Configuration (`~/.apollo/`)

~/.apollo/
├── config.json          # active profile and default projects
├── credentials.json     # tokens (mode 0600 — the only secret-bearing file)
├── checkouts.json       # known-checkouts registry
└── baselines/           # sync hashes for diff/push

Never read, print, copy, or commit ~/.apollo/credentials.json — it holds your access and refresh tokens. All other commands need no additional secrets.

Environment Variables

Environment variables override file-based configuration — useful for CI/CD pipelines.

Variable	Description
`APOLLO_TOKEN`	Skip login — authenticate with this token directly (CI auth)
`APOLLO_PROFILE`	Select the credential profile
`APOLLO_ORG_ID`	Organization ID override
`APOLLO_PROJECT_ID`	Project ID override
`APOLLO_RUNTIME_VERSION`	Override the checkout’s pinned runtime version
`APOLLO_TIMEOUT_MS`	Request timeout in milliseconds
`APOLLO_TUI`	`0` keeps a bare `apollo` on the CLI welcome instead of the TUI
`APOLLO_*_URL`	Per-service endpoint overrides

# Example: authenticate non-interactively in CI
export APOLLO_TOKEN="$CI_APOLLO_TOKEN"
apollo --json validate

Output & Exit Codes

With the global --json flag, every command emits a stable envelope on stdout:

{ "success": true, "data": { } }

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "…", "suggestion": "…" } }

Exit code	Meaning
`0`	Success
`1`	Runtime/API failure
`2`	Validation failure
`3`	Authentication/configuration failure

--verbose streams one redacted line per API request to stderr (auth/token/key/secret values never appear); the TUI shows the same stream live in its activity drawer.

CLI

Configuration

Checkout Structure

The `.apollorc` Binding

User Configuration (`~/.apollo/`)

Environment Variables

Output & Exit Codes

Next Steps

Command Reference

Workflows

​Checkout Structure

​The .apollorc Binding

​User Configuration (~/.apollo/)

​Environment Variables

​Output & Exit Codes

​Next Steps

Command Reference

Workflows

Checkout Structure

The `.apollorc` Binding

User Configuration (`~/.apollo/`)

Environment Variables

Output & Exit Codes

Next Steps