Cowboy: Autonomous Agent Harness for NixOS
<!-- Simple valid SVG -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 200" style="width: 100%; height: 100%;">
<defs>
<linearGradient id="hatGradient" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#8B4513"/>
<stop offset="100%" stop-color="#654321"/>
</linearGradient>
<linearGradient id="bandGradient" x1="0" y1="0" x2="1" y2="0">
<stop offset="0%" stop-color="#B8860B"/>
<stop offset="100%" stop-color="#DAA520"/>
</linearGradient>
</defs>
<!-- Hat shadow -->
<ellipse cx="150" cy="190" rx="120" ry="15" fill="rgba(0,0,0,0.1)"/>
<!-- Hat brim -->
<ellipse cx="150" cy="143" rx="138" ry="25" fill="url(#hatGradient)" stroke="#654321" stroke-width="1.5"/>
<!-- Hat crown -->
<path d="M85,143 Q85,100 95,78 L100,68 Q120,42 150,35 Q180,42 200,68 L205,78 Q215,100 215,143"
fill="#A0522D" stroke="#654321" stroke-width="1.5"/>
<!-- Hat band -->
<path d="M88,118 Q88,108 150,102 Q212,108 212,118 Q212,126 150,120 Q88,126 88,118"
fill="url(#bandGradient)" stroke="#8B6914" stroke-width="0.8"/>
<!-- Star -->
<polygon points="150,106 152,109 155,109 153,111 154,114 150,112 146,114 147,111 145,109 148,109"
fill="#FFD700" stroke="#B8860B" stroke-width="0.5"/>
</svg>
</div>
<div id="hatMessage" style="font-family: Georgia, serif; font-size: 1.8rem; color: #8B4513; margin-top: 1rem; font-weight: bold;">
Yeehaw! 🤠
</div>
<div style="font-style: italic; color: #A0522D; margin-top: 0.5rem;">
Saddle up for autonomous AI adventures
</div>
Cowboy is a production-ready AI agent harness that transforms natural language requests into safe, auditable system operations. Built on Zellij and WebAssembly, it provides a secure, memory-aware execution environment for autonomous AI agents on NixOS systems.
What is Cowboy?
Cowboy bridges the gap between large language models and practical system automation. Unlike traditional CLI tools or API clients, Cowboy provides a complete execution environment where AI agents can:
- Execute tools safely within configured security boundaries
- Maintain persistent memory across sessions and conversations
- Orchestrate sub-agents for parallel task execution
- Integrate natively with NixOS, home-manager, and system configuration
Think of Cowboy as the "operating system" for AI agents—providing the runtime, security model, and tooling that autonomous agents need to interact with your systems effectively.
Target Audience
👨💻 Developers
Automate development workflows with AI assistance—from code review to deployment pipelines. Cowboy agents can read, write, search, and execute code while maintaining security boundaries.
🔧 System Administrators
Manage NixOS infrastructure declaratively with AI-powered automation. Deploy configurations, monitor systems, and troubleshoot issues with human-in-the-loop approval.
🔬 Researchers
Experiment with autonomous agent systems in a controlled, observable environment. Cowboy provides complete audit trails and reproducible execution contexts.
🏢 Teams
Implement AI-assisted workflows with proper governance. Cowboy's approval system and audit logging ensure compliance while enabling productivity gains.
Key Features
🔒 Security-First Architecture
Every tool call passes through configurable security filters. Network namespaces isolate agents, while a credential-injecting proxy ensures API keys are never exposed to the agent directly.
🧠 Persistent Memory System
Agents learn from past interactions and build institutional knowledge. The memory backend supports session persistence, context retrieval, and long-term knowledge storage.
⚡ Real-Time Execution
Tools run in your actual environment, not simulated sandboxes. Cowboy executes commands directly on your system while maintaining strict security boundaries.
🔄 Sub-Agent Orchestration
Parallel task execution with delegated authority. Cowboy can spawn multiple agent instances that work together on complex tasks while maintaining coordinated security policies.
🔧 NixOS Integration
Native support for Nix flakes, home-manager, and declarative system configuration. Cowboy agents understand Nix-specific operations and can manipulate configurations safely.
📊 Complete Audit Trail
Every action is logged with approval states and execution context. Full observability into agent behavior for compliance and debugging.
Architecture Overview
Cowboy follows a modular, layered architecture:
┌─────────────────────────────────────────────────────────┐
│ Zellij Session │
├─────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────────────┐ │
│ │ Cowboy Plugin (WASM) │ │
│ │ ┌─────────┐ ┌──────────┐ ┌─────────────────┐ │ │
│ │ │ UI │ │ Agent │ │ Tool Executor │ │ │
│ │ │ /TUI │ │ Loop │ │ (RunCommands) │ │ │
│ │ └─────────┘ └────┬─────┘ └────────┬────────┘ │ │
│ │ │ │ │ │
│ │ ┌─────────┐ ┌────▼─────┐ ┌────────▼────────┐ │ │
│ │ │Provider │ │ Context │ │ Filter Pipeline │ │ │
│ │ │Traits │ │ Manager │ │ (Compiled) │ │ │
│ │ │(Claude/ │ │(Session/ │ └──────────────────┘ │ │
│ │ │ GPT) │ │ Compact) │ │ │
│ │ └─────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
┌──────▼──────┐
│ Proxy Layer │ (Credential injection,
│ + Network │ method gating, topology
│ Namespace │ isolation)
└──────┬──────┘
│
┌──────▼──────┐
│ LLM API │
│(Claude/GPT) │
└─────────────┘
Core Components
- WASM Plugin Runtime - Executes in Zellij as a WebAssembly plugin, providing the agent runtime environment
- Security Filters - Compiled Rust middleware that cannot be modified at runtime
- Provider Abstraction - Type-safe interface for different LLM providers (Claude, OpenAI, local models)
- Memory Backend - Persistent storage for session data and long-term knowledge
- Bridge Services - External platform integration (Discord, Email) via Redis Streams
- NixOS Modules - Declarative configuration for system integration
Design Principles
- No /tmp/ -- Full observability through persistent storage
- Nix-native -- All configuration via NixOS/home-manager modules
- Space is cheap -- Log everything, compress later
- Tee-style I/O -- Never block on disk operations
- Compiled security -- Filters are Rust, not runtime-modifiable
- Topology-based isolation -- Network namespace + proxy, not iptables rules
Getting Started
Ready to try Cowboy? Get up and running in minutes:
# Install via pip
pip install get-cowboy
# Start your first agent session
cowboy --model anthropic:claude-opus-4-6
For NixOS users, Cowboy provides full system integration:
# In your NixOS configuration:
imports = [ inputs.cowboy.nixosModules.default ];
services.agent = {
enable = true;
provider = "anthropic";
model = "claude-opus-4-6";
};
Next Steps
- Installation - Set up Cowboy on your system
- Quickstart - Your first agent session in 5 minutes
- Configuration - Advanced setup and customization
- Architecture - Deep dive into Cowboy's design
- Security Model - Understanding the security boundaries
Join the Community
Cowboy is built for developers, sysadmins, and researchers who want to harness the power of AI agents safely and effectively. Whether you're automating your development workflow, managing NixOS infrastructure, or experimenting with autonomous systems, Cowboy provides the foundation you need.