Skip to content

Quickstart

This quickstart takes you from nothing installed to a real agent running under enforcement: its outbound calls are checked against policy, allowed or denied, and written to the audit log.

The default install path uses precompiled static binaries. You do not need a build toolchain, or any API keys, unless you choose to build from source.

OpenFirma can be installed with a one-line script or built from source. The script downloads the right binary for your platform, puts it on your PATH, and offers to scaffold your first project.

  1. Run the installer.

    On Linux and macOS:

    Terminal window
    curl -fsSL https://install.openfirma.ai | sh

    On Windows (PowerShell):

    Terminal window
    iwr -useb https://install.openfirma.ai/install.ps1 | iex
  2. Confirm firma is on your PATH.

    Terminal window
    firma --version

    If the command is not found, open a new terminal so your shell picks up the updated PATH, then try again.

The installer drops firma in ~/.local/bin by default and adds that directory to your shell’s PATH. It keeps backend support binaries in a private libexec/openfirma directory beside firma. These support binaries are not commands and must not be added to PATH.

The installer downloads checksum-verified release archives and does not use Homebrew. On Apple silicon it installs the native arm64 build even when the shell runs under Rosetta. It replaces only a firma in its own install directory. If another firma, such as one from cargo install, comes earlier on PATH, the installer warns that it shadows the new one; remove it or reorder PATH.

Linux and macOS installs are serialized per destination and restore the previous private runtime shim after ordinary failures or caught INT, HUP, and TERM signals. Because the CLI and its private shim live at separate paths, SIGKILL or power loss during the final replacement can still leave a mixed installation; rerun the installer to repair it.

The Windows installer installs only firma.exe. It does not install the optional secret shim from release archives: CLI secret-provider mediation is not supported by the current Windows/WSL2 compatibility backend, and the installer does not attempt WSL mediation.

Start in the project directory you want to protect. Scaffold a local OpenFirma layout for this demo:

Terminal window
firma config --yes \
--name quickstart \
--posture dev \
--mapping github \
--extra-hosts api.github.com

This creates .firma/ with a unified firma.toml (authority, sidecar, and run profiles), mapping files, policy files, and local signing material under the platform state directory. The GitHub mapping enables HTTPS interception for api.github.com; --extra-hosts adds a catch-all rule for the public profile endpoint used below.

firma run launches a command inside a sandbox and routes its outbound traffic through the enforcement Sidecar. Unless you point it at an already-running stack, it autostarts a local Sidecar and a local Authority, then tears down whatever it started when the command exits.

The command after -- is whatever you want to govern. Here it’s a one-line curl to keep the demo dependency-free, but in practice it could also be an AI agent such as Claude Code or Codex — see Secure a local coding agent. Inside the sandbox, firma run sets HTTP_PROXY / HTTPS_PROXY so cooperative clients route through the Sidecar; on Linux the sandbox also confines traffic structurally, so even a process that ignores those variables can’t bypass it (how interception works).

On Linux, firma run uses the bwrap backend and structurally confines outbound traffic.

On macOS and Windows (WSL2), the default backends (vz and wsl2) provide proxy-only enforcement: traffic is mediated for cooperative HTTP clients like curl, but firma run requires an explicit opt-in before starting. Pass --allow-non-structural, or set allow_non_structural = true under [run.defaults] in .firma/firma.toml. See The sandbox boundary for details.

Terminal window
firma run --config .firma/firma.toml -- \
curl -kfsS https://api.github.com/users/firma-ai

Every outbound call the wrapped command makes is normalized, checked against its capability, and evaluated against the Cedar policy bundle supplied by the Authority. -k just lets this single curl skip certificate setup; for real agents firma run installs and trusts its generated CA inside the sandbox automatically, so you rarely need it. To inspect or install that CA yourself, see Enable HTTPS MITM.

After the command exits, read the audit log:

Terminal window
firma monitor --no-follow --format json

Each line is one signed execution event. For the GitHub call, expect ALLOW events ("decision":1) for resources like api.github.com/ and api.github.com/users/firma-ai.

For this run, three local pieces work together (autostarted on demand, or reused if already running):

  • An Authority, which signs a capability token and streams policies and revocations.
  • A Sidecar, which receives outbound requests and decides ALLOW or DENY.
  • Your wrapped command, sandboxed and routed through the Sidecar. On Linux (bwrap), egress is structurally confined; on macOS and WSL2, enforcement is proxy-based and depends on the agent honoring HTTP_PROXY.

Every request takes the same path:

flowchart LR
    agent["Wrapped agent"] -->|"Outbound request"| sidecar["Sidecar"]
    sidecar --> normalizer["Normalizer"]
    normalizer --> stage1["Stage 1: Capability validation"]
    stage1 --> stage2["Stage 2: Policy evaluation"]
    stage2 -->|"ALLOW"| forwarded["External service"]
    stage2 -->|"DENY"| denied["403 response"]
    stage2 --> audit["Signed audit event"]
    authority["Authority"] -. "Capability and policy stream" .-> sidecar

The important detail is that the Sidecar does not ask the Authority on every request. Once it has the public key, policy bundle, capability seed, and revocation state, the decision path is local.

Stage 1 checks whether the agent has a valid capability for the normalized action. Stage 2 evaluates the current Cedar policy. Both stages must pass before the call is forwarded.

The rest of the docs are organized from mental model to hands-on work.

Start with these Concepts pages:

  1. Architecture & invariants — the three processes and the four design invariants everything else builds on.
  2. The enforcement pipeline — the stage chain in detail.
  3. Action classes — the canonical vocabulary that connects raw HTTP traffic to policy.
  4. Capabilities and Policies — the two layers that decide what an agent may do.

Then move to the guide that matches your next task: