Design Overview

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 launches have different credential and process boundaries. The OCI runtime is a specialized optional route for Cowboy’s own payload. See Deployment Paths for that choice before selecting a host or changing its controls.

Core and the two hosts

The core owns the agent loop, provider request formatting, tools, session state, memory and message polling. Two hosts run it:

Zellij implements asynchronous commands, HTTP requests, timers and peer spawning through its plugin API. Montana implements those operations natively and delivers completions to the component. Both use the same semantic intents and provider logic; terminal navigation and pane controls belong to Zellij. Montana runs peers as component instances on separate threads in the same process, sharing its filesystem view and HTTP client.

Two paths to the outside world

Custom asynchronous effects cross the core’s host interface: execution, HTTP, timers and peer lifecycle requests. The component adapter maps these to WIT imports. An effect request does not grant permission to perform it.

Direct filesystem access is a separate path. Montana gives the component WASI preopens for its resolved workspace, home, config, data and temporary directories. Config loading, plan persistence and other direct file operations use those preopens without an execution effect. WASI clocks and randomness are also available; WASI sockets are not enabled.

Montana maps each preopened host directory to the same guest path. This matters because execution effects run native processes: a path computed in the guest must name the same file when passed to a shell command.

To reason about access, inspect both the host’s effect handling and its WASI grants, then the enclosing process identity, mounts and network policy. Sheepdog’s tool-command policy alone does not describe direct guest file access. See Security Model.

Launch branches

cowboy-core
├── Zellij plugin: interactive terminal
└── WASI component → Montana
    ├── managed NixOS: systemd agent service
    ├── local headless launch
    ├── ordinary Docker: image supervisor
    └── optional Cowboy OCI runtime: embedded Montana

The managed daemon runs Montana directly with a per-agent component, under the shared systemd hardening envelope, agent user, configured network namespace, credential proxy and Sheepdog policy. It does not launch the agent through the OCI runtime. Optional socket forwarders use a helper from that runtime package; that does not turn the daemon into an OCI container.

Local and ordinary Docker launches hold provider credentials. The managed proxy deployment keeps them outside the agent. The OCI route has its own mount, seccomp and egress controls; it is not a general container runtime. Tool behavior can differ under these policies. The terms bare, user and container classify a design progression; they are not three switches offered by the runtime binary.

Messages and configuration

Bridge services connect external platforms to Redis streams. Core polls its configured sources and sends replies through their outboxes. Bridge approval can hold an outbound message for a human decision. Recovery does not guarantee completion or preserve reply routing across a restart; see Inbound Message Reliability.

Both hosts pass a flat string configuration map to core. The CLI, persistent JSON, generated NixOS configuration and secret discovery are different inputs; see Configuration. Skills, tools and bridges extend the agent through the module interface.

Implementation map

The Component ABI describes WIT and the native control protocol. The embedding guide explains how to add a host.