backends

Override the configured backend for a single invocation without editing config. Flags are global — they work on any ace subcommand.

$ ace --codex # launch Codex for this session only
$ ace --claude -- --continue # resume with Claude, passing --continue through
$ ace mcp --codex # list Codex MCP servers without switching config

Schools, users, or projects can register additional backend entries via keyed [backends.<name>] tables; the table key is the backend's name. A custom backend aliases a built-in kind (claude, codex, opencode, or pi) and may override its launch cmd and env, and set a model and effort. The MCP, instructions file, and linked-folder behavior are inherited from the aliased kind.

# Override env on the built-in claude backend
[backends.claude]
env = { ANTHROPIC_BASE_URL = "https://proxy.example.com" }

# Custom name aliasing claude
[backends.bailer]
kind = "claude"
env = { ANTHROPIC_BASE_URL = "https://bailer.example.com" }

# Wrap the claude binary through a process wrapper
[backends.claude-wrapped]
kind = "claude"
cmd = ["wrapper", "claude"]

model and effort

model and effort map to each backend's native settings, for interactive sessions and one-shot ace -p runs. Both are passed through unchanged — ACE does not validate them. Unset, the backend uses its own default. A custom backend inherits the mapping of its kind. Arguments after -- come last, so they can override either value for one run.

# Pin the built-in claude backend's model and effort
[backends.claude]
model  = "opus"
effort = "high"

$ ace config set backends.claude.model opus # same, from the CLI
$ ace config explain backends.claude.model # which layer sets it

templated cmd and env

cmd[] and env values support {{ placeholder }} substitution when ACE resolves the backend. A school can provide a backend that points at a launcher script under its own clone without knowing the absolute path.

# School-relative launcher script
[backends.codex-ace]
kind = "codex"
cmd  = ["{{ school_dir }}/skills/ace-connect/scripts/codex.sh"]

# Path-valued env var
[backends.claude-scoped]
kind = "claude"
env  = { XDG_CONFIG_HOME = "{{ project_dir }}/.config" }

Selectable via backend = "bailer" in any config layer or -b bailer on the CLI. Layer order for merging [backends.<name>] tables is school → user → project → local; later layers may add new tables or partially override a table of the same name from an earlier layer. A custom backend cannot introduce new behavior beyond its aliased kind — that requires a source change.

ACE links school folders into the project's backend directory. skills/ becomes a real directory with per-skill symlinks (driven by skills/include_skills/exclude_skills in ace.toml); the rest are whole-directory symlinks. Not all backends support every folder.

Trust modes request backend-specific permission behavior. default uses the backend's standard handling, while auto and yolo map to different flags where each backend supports them. Three equivalent ways to persist the mode:

For a single invocation without writing to disk, pass --trust <mode>, or its shortcuts --auto and --yolo.

scope

Without a scope flag, trust writes to ace.local.toml (per-machine and gitignored). Trust is personal configuration: use local scope for this project or user scope across projects, not project scope.

Omitting trust inherits the level from lower-precedence layers. An explicit trust = "default" — in a personal layer or via --trust default — overrides an inherited auto or yolo.

# Per-machine yolo for the current project (default scope)
$ ace yolo

# User-wide auto across every project on this machine
$ ace config set trust auto --user

# Inspect which layer is winning and why
$ ace config explain trust

per-backend mapping

ACE registers [[mcp]] entries from school.toml into the active backend. All entries are remote HTTP endpoints.

ACE checks whether the backend is authenticated before launching a session.