Installation

Cowboy is an AI agent harness built on Zellij and WebAssembly, providing secure, reliable tooling for autonomous AI agents. This guide covers all installation methods from simple to advanced.

Quick Start

If you just want to get started quickly:

Nix users:

nix profile install github:dmadisetti/cowboy
cowboy --version

Python users:

pip install get-cowboy
cowboy --version

For detailed installation instructions, continue reading below.

Prerequisites

Before installing Cowboy, ensure you have the following:

Required Prerequisites

  • Nix (for Nix-based installation) or NixOS system
  • Git for fetching source code and flakes
  • Zellij terminal multiplexer (required for Cowboy to function)
  • Python 3.12+ (for pip installation method)

Optional Prerequisites

  • API keys for AI providers (Anthropic, OpenAI, etc.)
  • Home Manager (for user-level Nix configuration)
  • Docker/Podman (for container deployment)

Installing Zellij

Zellij is essential for Cowboy to function. Install it via your preferred method:

# Nix users
nix-env -iA nixpkgs.zellij

# Cargo users
cargo install zellij

# macOS users
brew install zellij

Verify Zellij is installed:

zellij --version

Installation Methods

Choose the installation method that best fits your environment:

The Nix flake installation provides the most integrated experience with NixOS systems, including system-level service management and security features.

Option A: Direct Flake Installation

For quick evaluation or testing:

# Install globally to your user profile
nix profile install github:dmadisetti/cowboy

# Or run temporarily without installation
nix run github:dmadisetti/cowboy -- --help

Option B: Flake Input in Your Configuration

For permanent integration with your NixOS or Home Manager configuration:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    cowboy.url = "github:dmadisetti/cowboy";
  };

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

Option C: System-Level Service (NixOS)

Enable Cowboy as a system service with full NixOS integration:

# configuration.nix
{ config, pkgs, ... }:

{
  imports = [ inputs.cowboy.nixosModules.default ];

  services.cowboy = {
    enable = true;
    provider = "anthropic";
    model = "claude-opus-4-6";
    # Additional configuration...
  };
}

This provides:

  • Automatic startup with system boot
  • Systemd service management
  • Network namespace isolation
  • Heartbeat monitoring
  • Secure credential storage

Method 2: Python Package (Development & Evaluation)

Ideal for development, testing, or systems without Nix.

Option A: PyPI Installation

# Install from PyPI
pip install get-cowboy

# Verify installation
cowboy --version

Option B: Development Installation

For contributing to Cowboy or using the latest development version:

# Clone the repository
git clone https://github.com/dmadisetti/cowboy.git
cd cowboy

# Install in editable mode
pip install -e .

# Or use uv (recommended)
uv pip install -e .

Option C: Using uv Package Manager

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install cowboy
uv pip install get-cowboy

# Or run directly without installation
uvx --from get-cowboy cowboy --help

Method 3: Home Manager Module

For user-level installation on NixOS or any Nix system using Home Manager.

# home.nix
{ config, pkgs, inputs, ... }:

{
  imports = [ inputs.cowboy.homeModules.agent ];

  programs.cowboy = {
    enable = true;
    provider = "anthropic";
    model = "claude-opus-4-6";
    # Configuration options...
  };
}

Benefits of Home Manager installation:

  • User-specific configuration
  • No root privileges required
  • Integrated with your user environment
  • Automatic shell completion

Method 4: Container Deployment

For isolated deployment or containerized environments:

# Build the container image
nix build .#container

# Run with Docker
docker load < result
docker run -it cowboy:latest

# Or with Podman
podman load < result
podman run -it cowboy:latest

The container includes:

  • Zellij terminal multiplexer
  • Python runtime
  • Cowboy CLI
  • Essential system utilities (bash, coreutils, git, curl)

Verification Steps

After installation, verify that Cowboy is working correctly:

Basic Verification

# Check installation version
cowboy --version

# View available commands
cowboy --help

# Test the CLI entry point
python -m cowboy --help  # For Python installation

Functionality Test

Run a simple agent session to verify everything works:

# Start an interactive session (requires API key)
cowboy --model anthropic:claude-opus-4-6

# Or test with a specific task
cowboy --model anthropic:claude-opus-4-6 --task "List files in current directory"

Nix-Specific Verification

For Nix installations, verify flake integration:

# Check if cowboy is in your profile
nix profile list | grep cowboy

# Test flake evaluation
nix eval github:dmadisetti/cowboy#packages.x86_64-linux.default

# Run a quick test
nix run github:dmadisetti/cowboy -- --version

Troubleshooting Common Issues

Zellij Not Found

# Ensure Zellij is installed and in PATH
which zellij
zellij --version

# Add to PATH if needed
export PATH="$HOME/.cargo/bin:$PATH"

Python Package Import Errors

# Check Python version
python --version  # Should be 3.12+

# Reinstall if needed
pip install --force-reinstall get-cowboy

Nix Flake Evaluation Errors

# Update flake inputs
nix flake update

# Check flake structure
nix flake check

Configuration After Installation

Once Cowboy is installed, you may want to configure it:

Setting API Keys

# Create configuration directory
mkdir -p ~/.config/cowboy

# Set API keys in environment or config file
export ANTHROPIC_API_KEY="your-key-here"
# Or add to ~/.config/cowboy/config.yaml

First Time Setup

# Start interactive configuration
cowboy --configure

# Or manually create config
cowboy --init-config

See Configuration for detailed setup options.

Uninstallation

Removing Nix Installation

# Remove from Nix profile
nix profile remove cowboy

# Or if using flake input, remove from configuration
# and run:
nix-collect-garbage -d

Removing Python Installation

# PyPI installation
pip uninstall get-cowboy

# Development installation
pip uninstall -e .

Removing Home Manager Installation

# Remove from home.nix and run:
home-manager switch

Next Steps

Once installed and verified:

  1. Quickstart: Quickstart Guide - Your first agent session
  2. Configuration: Configuration - Advanced setup options
  3. Architecture: Architecture Overview - Understand how Cowboy works
  4. Guides: Guides - Specific use cases and workflows

Additional Resources

Support

If you encounter issues during installation:

  1. Check the troubleshooting section above
  2. Review the GitHub issues
  3. Join the community discussions
  4. For Nix-specific issues, check NixOS Discourse

Next: Quickstart Guide → Learn how to use Cowboy for your first agent session.