Deployment paths
Choose the boundary before installing. The strongest documented deployment is managed NixOS on Linux/x86-64. Local and ordinary Docker paths deliberately hold credentials; the optional OCI route runs Cowboy’s own payload. These paths do not form a ladder, and tool behavior depends on each path’s policy.
| Path | Host requirements | Process identity and controls | Credentials | Mutable state | Primary limitation |
|---|---|---|---|---|---|
| Local evaluation | Nix source build; Zellij for the UI; Linux or macOS with the dependencies | Invoking user; Zellij harness or native Montana | Environment, user/system key files, or readable agenix files | Local XDG data/config directories and workspace | File and shell tools have the user’s permissions; no managed proxy or service envelope |
| Managed NixOS | NixOS, Linux/x86-64; configured operator and provider secret | Configured agent user; Montana under systemd, shared hardening envelope, network namespace, credential proxy, Sheepdog, broker ACLs | Proxy-readable secret files outside the agent; agent receives placeholders | Agent home, configured writable mounts, broker/bridge state | Controls depend on configuration; readable data is not confidential from permitted egress |
| Ordinary Docker | Source-built image; Docker on a matching Linux image architecture | Container root; ordinary Docker isolation; wizard uses Zellij, settings-based service uses Montana | Mode 0600 key file in the configuration volume | Configuration and workspace volumes; explicitly persist the data directory | No managed credential proxy or Cowboy cage; settings-based CLI launch does not itself mount the default data directory |
| Optional OCI cage | Linux/x86-64, Nix-built seed/rootfs, registered Cowboy runtime and resolver, Docker, companion images | Bundle-selected uid/gid; Cowboy runtime runs linked Montana with bundle syscall/filesystem policy | OpenRouter credential in companion; placeholder in agent | Bundle-selected writable mounts; companion scratch on host | Current CLI companion supports OpenRouter only; Redis companion has no durable volume; not a general container runtime |
Managed NixOS
Nix builds a per-agent component and declares the daemon, tools, proxy, message access, and service controls. The daemon launches Montana directly under systemd. It joins the configured Cowboy network namespace; the shared service envelope limits its writable world to the agent home and declared mounts. Sheepdog mediates tool execution. The daemon requires the credential proxy.
The module can also build an OCI bundle. That bundle is a separate deployment artifact, not an intermediate step in the systemd daemon launch. “Production” here describes the intended supported configuration, not adoption or runtime certification.
Local and ordinary Docker
Local UI sessions use the Zellij harness. Local headless sessions use Montana. Changing hosts does not add the managed security controls.
The ordinary image has two startup paths. The interactive wizard launches Zellij. A settings-based first boot generates and builds a Nix configuration, then its supervisor launches Montana on a Unix socket. Both keep real keys inside the container. The Docker walkthrough sets an explicit persistent data directory for the interactive path.
The NixOS module’s legacy container supervisor is a separate development artifact. It must not be confused with the managed systemd service or with the ordinary image’s settings-based supervisor.
OCI and embedding
The OCI runtime accepts Cowboy payloads and a narrow lifecycle command surface. It does not run arbitrary image commands. See the OCI contract before integrating it with an engine.
A custom host can implement cowboy:agent@0.2.0, but must supply and authorize
its own effects and filesystem access. Component portability alone supplies
no host security policy. Bare, user, and container are design
classifications, not three runtime selectors.
Continue to Installation. The security model describes the conditions behind the controls in this table.