Skip to content

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.

Terminal window
firma config # interactive wizard
firma config --yes # non-interactive defaults
firma config --output-dir .local # specific output directory
firma config --yes --mode agent-local \
--profile codex --posture dev \
--mapping anthropic # scripted full setup

Config lands in .firma/ inside the current directory, or an explicit --output-dir:

FormDestination
(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.

Terminal window
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.pub

Leave 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.

ModeWhat it scaffolds
agent-localSidecar + co-located mini-authority ([authority] + [sidecar.authority])
agent-remoteSidecar only, pointing at an existing authority ([sidecar.authority])
authorityStandalone 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]
FlagDefaultDescription
--modewizard / agent-localWhat to configure: agent-local, agent-remote, or authority
--profilewizard / genericExecution profile written to [run].profile
--agent-idgenerated / promptRegistered agt_ TypeID written to [sidecar.authority].agent_id
--posturewizard / devCedar policy posture written under policies/
--mappingwizard / profile defaultMapping file(s) listed in [authority].mapping_rules_paths — repeat for multiple (agent-local / authority; rejected in agent-remote)
--extra-hostsnoneComma-separated extra hosts the agent may reach, written to mapping-rules.toml (agent-local / authority; rejected in agent-remote)
--workspaceCWDAgent 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 CWDWhere firma.toml, policies, and mappings are written
--state-dir$FIRMA_STATE_DIR / XDGKeys, revocations, generated CA
--authority-listen127.0.0.1:50051gRPC listen address (agent-local / authority modes only)
--authority-urlwizard promptAuthority URL for agent-remote mode
--authority-ca-certwizard prompt / noneAuthority CA cert PEM path for agent-remote mode; omit for a publicly trusted certificate
--authority-pub-keyadopted from state dirAuthority public key path
--yes / -yoffSkip all prompts; use existing values or flag defaults
--forceoffOverwrite existing files including the authority keypair
--dry-runoffPrint generated files to stdout without writing to disk
--list-templatesoffPrint 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.

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.

Terminal window
# Keep everything, explicitly replace the registered identity
firma config --yes --agent-id agt_01j0000000e008000000000001
# Preview what would change without writing
firma config --yes --dry-run
<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 start

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 modes
listen_addr = "127.0.0.1:50051"
policy_dir = "policies/"
# ...
[sidecar.authority] # agent-local and agent-remote modes
agent_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.

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.

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.