Customize the default config with firma config
firma run works out of the box with no prior setup: it auto-scaffolds a
default config the first time it runs in a directory. firma config lets
you override those defaults — posture, mappings, authority mode, workspace
path, and more. Run it when you want control over what firma run uses, or
to update an existing config.
Usage shapes
Section titled “Usage shapes”firma config # interactive wizardfirma config --yes # non-interactive defaultsfirma config --output-dir .local # specific output directoryfirma config --yes --mode agent-local \ --profile codex --posture dev \ --mapping anthropic # scripted full setupConfig lands in .firma/ inside the current directory, or an explicit
--output-dir:
| Form | Destination |
|---|---|
| (default) | .firma/ in current directory |
--output-dir <path> | <path> verbatim |
Connected Sidecars consume complete Authority mapping snapshots; there is no
mapping-source selector. agent-local generates mapping files for the local
mini-authority, which loads them through [authority].mapping_rules_paths.
agent-remote generates no local mappings and, on re-runs, removes the local
[authority] section with its mapping paths unless you choose to keep it.
Existing mapping files remain untouched, including with --force. --mapping
and --extra-hosts are rejected in remote mode. Every Sidecar requires an
Authority; unmatched traffic is always denied.
firma config --yes --mode agent-remote \ --agent-id agt_01j0000000e008000000000001 \ --authority-url https://authority.example.com:9443 \ --authority-ca-cert ./authority-ca.crt \ --authority-pub-key ./workspace.pubLeave out --authority-ca-cert when the Authority presents a publicly trusted
certificate: the Sidecar then verifies it against the platform’s trusted roots.
A CA already in firma.toml is kept for the same Authority host and port; to
stop pinning it, remove ca_cert_paths from [sidecar.authority]. Several
CAs, for a rotation, go in ca_cert_paths by hand; a rerun of firma config
keeps only the first.
Supply required Sidecar authentication separately. Per-run synthesis with SaaS credentials omits fallback mapping paths and files; explicit conflicting settings remain visible to Sidecar validation.
| Mode | What it scaffolds |
|---|---|
agent-local | Sidecar + co-located mini-authority ([authority] + [sidecar.authority]) |
agent-remote | Sidecar only, pointing at an existing authority ([sidecar.authority]) |
authority | Standalone authority server — no sidecar config |
firma config [--mode <mode>] [--profile <profile>] [--agent-id <agent-id>] [--posture <posture>] [--mapping <mapping>] [--extra-hosts <hosts>] [--workspace <dir>] [--output-dir <dir>] [--state-dir <dir>] [--authority-url <url>] [--authority-ca-cert <path>] [--authority-pub-key <path>] [--authority-listen <addr>] [--yes] [--force] [--dry-run] [--list-templates]| Flag | Default | Description |
|---|---|---|
--mode | wizard / agent-local | What to configure: agent-local, agent-remote, or authority |
--profile | wizard / generic | Execution profile written to [run].profile |
--agent-id | generated / prompt | Registered agt_ TypeID written to [sidecar.authority].agent_id |
--posture | wizard / dev | Cedar policy posture written under policies/ |
--mapping | wizard / profile default | Mapping file(s) listed in [authority].mapping_rules_paths — repeat for multiple (agent-local / authority; rejected in agent-remote) |
--extra-hosts | none | Comma-separated extra hosts the agent may reach, written to mapping-rules.toml (agent-local / authority; rejected in agent-remote) |
--workspace | CWD | Agent RW path for the sandbox. Written to firma.toml only when it differs from the project root (the directory holding .firma/), which firma run derives on its own |
--output-dir / -o | .firma in CWD | Where firma.toml, policies, and mappings are written |
--state-dir | $FIRMA_STATE_DIR / XDG | Keys, revocations, generated CA |
--authority-listen | 127.0.0.1:50051 | gRPC listen address (agent-local / authority modes only) |
--authority-url | wizard prompt | Authority URL for agent-remote mode |
--authority-ca-cert | wizard prompt / none | Authority CA cert PEM path for agent-remote mode; omit for a publicly trusted certificate |
--authority-pub-key | adopted from state dir | Authority public key path |
--yes / -y | off | Skip all prompts; use existing values or flag defaults |
--force | off | Overwrite existing files including the authority keypair |
--dry-run | off | Print generated files to stdout without writing to disk |
--list-templates | off | Print the posture × mapping catalogue and exit |
Mappings belong to the Authority that publishes them. In agent-remote mode,
configure mappings on the remote Authority; --mapping and --extra-hosts
are rejected there.
An explicit --posture rewrites the selected policies/<posture>.cedar
file even without --force; other existing generated files are still
preserved unless --force is set.
Select --mapping composio to protect hosted MCP and direct Composio execution
on app.composio.dev and backend.composio.dev. This mapping configures strict
HTTPS interception because CONNECT-only traffic does not expose the logical
tool action. See Govern Composio tool execution before enabling
it in production.
Re-running on an existing config
Section titled “Re-running on an existing config”When firma config finds firma.toml in the target directory, it reads the
current values and uses them as defaults for every prompt and non-interactive
run. Pass only the flags you want to change; everything else is preserved.
Non-interactive local re-runs preserve the complete
authority.mapping_rules_paths list, including custom files and an explicit
empty list, unless --mapping supplies a new selection. The Authority’s list
takes precedence over ignored connected-Sidecar mapping paths. An explicit
--extra-hosts request adds the generated mapping-rules.toml to that list if
it is not already loaded, so the new rules reach the connected Sidecar.
Changing an existing local-authority config to --mode agent-remote
normally removes the top-level [authority] section from the generated
firma.toml; otherwise firma run starts the Authority locally instead
of using only the remote Authority. Non-force runs warn about that.
Interactive runs ask whether to keep the section and use that answer to
rewrite firma.toml; non-interactive runs remove the section even without
--force. The command merges firma.toml on every run. Switching back to
agent-local removes the remote physical connection override, trust paths,
mTLS client identity, and PSK credentials so the Sidecar uses the local
mini-authority. Remote re-runs preserve those connection settings, except that a CA certificate is kept only for the same Authority host and port.
# Keep everything, explicitly replace the registered identityfirma config --yes --agent-id agt_01j0000000e008000000000001
# Preview what would change without writingfirma config --yes --dry-runScaffolded layout
Section titled “Scaffolded layout”<output-dir>/ # project-local config dir firma.toml # unified config (authority + sidecar + run profiles) mapping-rules.toml # base routing rules (`agent-local`/`authority` only) mappings/<name>.toml # one file per selected mapping (`agent-local`/`authority` only) policies/<posture>.cedar # Cedar enforcement policy issuance-policies/ issuance.cedar # token issuance policy
<state-dir>/ # user-global state (XDG default) authority.key # Ed25519 signing key — never commit authority.pub # matching public key audit.key # audit signing key revocations.txt # empty revocations list tls/ # self-signed TLS material generated-firma-ca/ # populated by sidecar on first startGenerated firma.toml structure
Section titled “Generated firma.toml structure”agent-local emits both sections. agent-remote emits only the
[sidecar.authority] connect block. authority mode emits only
[authority].
No artifact path is written. The signing key, revocations, TLS material, audit log and key, and MITM CA all have defaults that resolve to the state directory this run generated them in, so naming them would only pin the file to this machine. Each key stays available as an override.
[authority] # agent-local and authority modeslisten_addr = "127.0.0.1:50051"policy_dir = "policies/"# ...
[sidecar.authority] # agent-local and agent-remote modesagent_id = "agt_01j0000000e008000000000001"url = "http://127.0.0.1:50051"# `agent-remote` also carries public_key_path, and ca_cert_paths for a private# CA: a remote Authority's anchors are operator-supplied; there is no default.# ... plus connect_timeout / reconnect_* / revocation_* tuning
# Uncomment for remote Authorities that require Sidecar PSK authentication.# [sidecar.authority.credentials]# workspace_id = "ws-acme"# sidecar_id = "sc-eu-1"# pre_shared_key_env = "FIRMA_SIDECAR_PSK"
[run]profile = "codex"Firma rejects unknown keys at every level. The only top-level sections are
[authority], [sidecar], and [run]; a typo in any nested table or any Run
profile—including one that is not selected—fails parsing instead of being
silently ignored. Dynamic profile and credential labels remain allowed, but
their contents are strict.
The two values are intentionally independent. agent_id is the stable UUID
assigned during Authority registration and used in capability, audit, and
transport attribution. [run].profile selects local execution behavior such
as mounts and environment variables; it is never sent as the capability
request’s agent identity.
For agent-local, a new config generates an agt_ TypeID backed by UUIDv7 when
--agent-id is omitted. For agent-remote, copy the agent_id returned by
FirmaTeam registration and pass it with --agent-id; non-interactive setup
requires the flag. Re-running firma config preserves a valid existing agent
ID unless the flag replaces it.
Implicit init on firma run
Section titled “Implicit init on firma run”firma run checks for a discoverable firma.toml at launch. If none is
found, it scaffolds one with non-interactive defaults and proceeds. This
keeps firma run codex working from a fresh clone without any prior setup.
Common gotchas
Section titled “Common gotchas”Wizard refuses to run in CI. firma config without --yes requires a
TTY. Pass --yes in non-interactive contexts.
firma.toml already exists. The command merges configuration changes and
preserves comments and unrelated settings. Existing mapping files remain on disk
when switching to remote mode; --force is not required to apply that conversion.
Keys must not go in the config dir. Keys live in <state-dir>, not
<output-dir>. Do not commit authority.key. Add .firma/*.key to
.gitignore.
See also
Section titled “See also”- Start and monitor the daemon — what to do after
firma config. - Wrap an agent with
firma run— the one-command path that callsfirma configimplicitly. - Configuration reference — the full
firma.tomlschema.