Installation

Cowboy runs in two modes:

Lite — pip install, portable, no NixOS. The agent runs in your terminal with the core tools.
Full (NixOS) — agents run as managed services with network isolation, credential injection, and seccomp confinement.

Both modes require Zellij on PATH — the agent runtime is a Zellij plugin. The Nix packages pull it in for you; for the pip install you provide it yourself.

Lite (pip)

pip install get-cowboy        # PyPI package is "get-cowboy", binary is "cowboy"
cowboy --version

If you don’t already have Zellij:

nix-env -iA nixpkgs.zellij    # or: cargo install zellij / brew install zellij

You can also run it without installing, via uv:

uvx --from get-cowboy cowboy --help

Nix (CLI only)

The default flake package is the WASM plugin, so install the CLI package explicitly:

# Install the cowboy CLI into your profile
nix profile install github:dmadisetti/cowboy#get-cowboy

# Or run it without installing
nix run github:dmadisetti/cowboy#get-cowboy -- --help

Full (NixOS module)

Add the flake input and import the module, then enable one or more agents under services.cowboy.agents.<name>:

# flake.nix
{
  inputs.cowboy.url = "github:dmadisetti/cowboy";

  outputs = { self, nixpkgs, cowboy, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        cowboy.nixosModules.default
      ];
    };
  };
}

# configuration.nix
{
  services.cowboy.agents.dev = {
    enable = true;
    user = "alice";
    model = "claude-sonnet-4-20250514";
  };
}

This gives each agent a systemd-managed session, a network namespace forced through the credential proxy, optional seccomp confinement (services.cowboy.sheepdog), and optional message bridges (services.cowboy.bridges). The full set of per-agent options lives in Configuration.

macOS is supported via cowboy.darwinModules.default (launchd + pf instead of systemd + netns). Seccomp confinement is Linux-only.

Container

nix build .#docker-image
docker load < result          # loads cowboy:latest (or: podman load < result)
docker run -it cowboy:latest

The image bundles Zellij, the Python CLI, the harness plugin, and the bridge services.

Configuration after install

Set provider credentials as environment variables (lite mode) or via the NixOS module (full mode). Config files are JSON, read in order of increasing precedence:

/etc/cowboy/config.json      # optional hand-written system defaults (not emitted by the NixOS module)
~/.config/cowboy/config.json # user overrides
.cowboy/config.json          # project overrides (lite mode)

export ANTHROPIC_API_KEY="sk-ant-..."
export EXA_API_KEY="..."      # optional, for web search

See Configuration for the full key reference.

Next steps

Quickstart — your first session
Configuration — config files, flags, and module options

Keyboard shortcuts