zeroclaw-ai-agent-runtime

What this skill does

```markdown
---
name: zeroclaw-ai-agent-runtime
description: Expertise in ZeroClaw — the fast, lean, fully autonomous AI agent infrastructure written in Rust with swappable providers, channels, and tools
triggers:
  - set up zeroclaw agent infrastructure
  - deploy zeroclaw on edge hardware
  - configure zeroclaw provider or model
  - zeroclaw tool and channel integration
  - build agentic workflow with zeroclaw
  - zeroclaw cli commands and configuration
  - swap zeroclaw provider or memory backend
  - troubleshoot zeroclaw agent runtime
---

# ZeroClaw AI Agent Runtime

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

ZeroClaw is a zero-overhead, fully autonomous AI agent runtime written in Rust. It runs on <5MB RAM, starts in <10ms, and ships as a single static binary for ARM, x86, and RISC-V. Its trait-driven architecture makes every core system (LLM providers, communication channels, tools, memory backends, tunnels) hot-swappable without recompiling.

---

## Installation

### One-Click Setup (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
```

### Build from Source

```bash
# Prerequisites: Rust stable toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# Release build (optimised, small binary)
cargo build --release

# Verify binary size and startup performance
ls -lh target/release/zeroclaw
/usr/bin/time -l target/release/zeroclaw --help   # macOS
/usr/bin/time    target/release/zeroclaw --help   # Linux
```

### Verify Installation

```bash
zeroclaw --version
zeroclaw status
```

---

## Core Concepts

| Concept | Description |
|---|---|
| **Provider** | LLM backend (OpenAI, Anthropic, local, custom OpenAI-compatible) |
| **Channel** | Input/output surface (CLI, HTTP, WebSocket, Slack, etc.) |
| **Tool** | Capability exposed to the agent (shell, browser, file I/O, custom) |
| **Memory** | Conversation + long-term storage backend (in-memory, vector DB, etc.) |
| **Tunnel** | Secure inbound connectivity (ngrok-style) for remote channels |
| **Workspace** | Scoped working directory with allowlisted paths and tool access |

---

## Configuration

ZeroClaw uses a TOML config file. Default location: `~/.zeroclaw/config.toml` (override with `--config`).

### Minimal Config

```toml
# ~/.zeroclaw/config.toml

[provider]
kind = "openai"                         # or "anthropic", "ollama", "custom"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"         # env var name, never hardcode

[channel]
kind = "cli"

[workspace]
root = "/home/user/projects"
allow = ["/home/user/projects"]        # explicit allowlist — nothing outside is accessible
```

### Full Config with All Sections

```toml
[provider]
kind       = "openai"
model      = "gpt-4o-mini"
api_key_env = "OPENAI_API_KEY"
base_url   = "https://api.openai.com/v1"   # override for OpenAI-compatible endpoints
timeout_s  = 60
max_tokens = 4096

[channel]
kind = "http"
host = "127.0.0.1"
port = 8080

[memory]
kind     = "sqlite"
path     = "~/.zeroclaw/memory.db"
max_msgs = 512

[tools]
allow = ["shell", "read_file", "write_file", "http_fetch"]
deny  = []                                  # explicit deny list

[tunnel]
enabled  = false
provider = "cloudflare"                     # or "ngrok"

[workspace]
root  = "/home/user/work"
allow = ["/home/user/work", "/tmp/zeroclaw"]

[logging]
level = "info"      # trace | debug | info | warn | error
format = "pretty"   # pretty | json
```

### Environment Variables

```bash
export OPENAI_API_KEY="sk-..."          # OpenAI
export ANTHROPIC_API_KEY="sk-ant-..."  # Anthropic
export ZEROCLAW_CONFIG="/etc/zeroclaw/config.toml"
export ZEROCLAW_LOG="debug"
export ZEROCLAW_WORKSPACE="/opt/agent-work"
```

---

## CLI Reference

### Global Flags

```bash
zeroclaw [--config <path>] [--log <level>] <subcommand>
```

### Key Commands

```bash
# Show runtime status and loaded config
zeroclaw status

# Start interactive CLI agent session
zeroclaw run

# Start agent as a background daemon
zeroclaw daemon start
zeroclaw daemon stop
zeroclaw daemon status
zeroclaw daemon logs --follow

# Run a single task and exit (headless / scriptable)
zeroclaw exec "summarise the file ./report.md and save the summary to ./summary.md"

# Provider management
zeroclaw provider list
zeroclaw provider test              # fires a test ping to the configured provider
zeroclaw provider set openai        # switch active provider

# Tool management
zeroclaw tool list
zeroclaw tool enable  http_fetch
zeroclaw tool disable shell

# Memory operations
zeroclaw memory list
zeroclaw memory clear               # wipe current session
zeroclaw memory export ./backup.json
zeroclaw memory import ./backup.json

# Workspace operations
zeroclaw workspace init /path/to/project
zeroclaw workspace allow /path/to/extra-dir
zeroclaw workspace show

# Pairing (for remote channel auth)
zeroclaw pair --channel http        # prints a one-time pairing code
```

---

## Rust Library Usage

ZeroClaw exposes its internals as a Rust library for embedding or extension.

### Add to `Cargo.toml`

```toml
[dependencies]
zeroclaw = { git = "https://github.com/zeroclaw-labs/zeroclaw.git", features = ["full"] }
tokio    = { version = "1", features = ["full"] }
```

### Minimal Embedded Agent

```rust
use zeroclaw::{
    agent::Agent,
    config::{Config, ProviderConfig, ChannelConfig, WorkspaceConfig},
    provider::openai::OpenAiProvider,
    channel::cli::CliChannel,
    tools::ToolRegistry,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load from env — never hardcode keys
    let api_key = std::env::var("OPENAI_API_KEY")
        .expect("OPENAI_API_KEY must be set");

    let config = Config {
        provider: ProviderConfig::openai("gpt-4o-mini", api_key),
        channel:  ChannelConfig::cli(),
        workspace: WorkspaceConfig::new("/tmp/agent-workspace")
            .with_allow("/tmp/agent-workspace"),
        ..Default::default()
    };

    let provider = OpenAiProvider::from_config(&config.provider)?;
    let channel  = CliChannel::new();
    let tools    = ToolRegistry::from_config(&config.tools);

    let mut agent = Agent::builder()
        .provider(provider)
        .channel(channel)
        .tools(tools)
        .config(config)
        .build()?;

    agent.run().await
}
```

### Custom Provider (Trait Implementation)

```rust
use async_trait::async_trait;
use zeroclaw::provider::{Provider, ProviderRequest, ProviderResponse};

pub struct MyLocalProvider {
    endpoint: String,
}

#[async_trait]
impl Provider for MyLocalProvider {
    async fn complete(
        &self,
        request: ProviderRequest,
    ) -> anyhow::Result<ProviderResponse> {
        // Call your local inference server
        let client = reqwest::Client::new();
        let res = client
            .post(&self.endpoint)
            .json(&request)
            .send()
            .await?
            .json::<ProviderResponse>()
            .await?;
        Ok(res)
    }

    fn model_name(&self) -> &str {
        "local-llama3"
    }
}
```

### Custom Tool (Trait Implementation)

```rust
use async_trait::async_trait;
use zeroclaw::tools::{Tool, ToolCall, ToolResult};

pub struct EchoTool;

#[async_trait]
impl Tool for EchoTool {
    fn name(&self) -> &str { "echo" }

    fn description(&self) -> &str {
        "Echoes the input string back to the agent"
    }

    fn parameters_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "text": { "type": "string", "description": "Text to echo" }
            },
            "required": ["text"]
        })
    }

    async fn invoke(&self, call: ToolCall) -> anyhow::Result<ToolResult> {
        let text = call.args["text"].as_str().unwrap_or("");
        Ok(ToolResult::text(text))
    }
}

// Register and use