Cowboy
Persistent agents on infrastructure you control.
Cowboy runs persistent AI agents on infrastructure you control, using Nix to configure their tools, credentials, message access, and approved actions.
The strongest documented deployment is managed NixOS on Linux/x86-64. Local and ordinary Docker paths have different boundaries and hold credentials locally. The OCI runtime is a specialized optional route for Cowboy’s own payload.
Why run an agent this way?
A maintenance task can produce a reviewed change without giving the agent the credential that publishes it. The repository’s effects runner check exercises adding a documentation post to a Git repository: it describes a commit bundle, applies it, and verifies the remote branch. This is a recorded test workflow, not a claim about production adoption.
In a deployment with the effects bridge and Discord approvals configured, the agent requests publication. The publishing runner checks the bundle and produces a card naming the target, execution identity, exact SHA, changed files, and diffstat. An authorized human reacts ✅ to push exactly that commit or ❌ to reject it. The runner executes under the configured publishing identity, checks policy again, and refuses a branch that moved after review. The result appears in the agent’s effects inbox and the configured operator status channel. Gated effects explains the configuration.
Choose a deployment
| Goal | Route | Boundary |
|---|---|---|
| Evaluate in a terminal | Local CLI and Zellij | Invoking user’s permissions; local credentials |
| Run a persistent managed service | NixOS systemd service running Montana | Per-agent component, shared service hardening envelope, network namespace, credential proxy, Sheepdog, and broker controls |
| Run on an ordinary Docker host | Self-contained image | Docker isolation; credentials in the container’s state volume |
| Integrate Cowboy’s payload with an OCI engine | Optional Cowboy OCI runtime | Bundle policy and configured cage; specialized command surface |
The full deployment matrix includes host requirements and state locations. “Production path” means the intended supported managed configuration, not measured adoption or general runtime certification. Its agent daemon runs Montana directly, without the OCI runtime.
Network restrictions, filesystem access, tool policy, and approval gates are separate controls. HTTP policy restricts methods and destinations; it does not promise that every permitted request leaves external state unchanged. Data an agent can read can leave through permitted requests or replies. Read the security model before granting sensitive access.
Start here
Continue to Installation, which maintains release availability and source-build instructions. Then use First request and daily operation and Troubleshooting.
Configuration explains how to change the
agent. Architecture explains the implementation
and the cowboy:agent@0.2.0 component contract.