ZeroClaw Agent Runtime

zerocode is the terminal interface for managing ZeroClaw. It is used for three primary tasks:

1. Managing Configuration: Use the Config pane to change settings (this is the preferred method for modifying ZeroClaw settings).
2. Interacting with Agents: Use the Code and Chat panes to drive agents.
3. Monitoring: Monitor your running ZeroClaw daemon.

zerocode connects to the daemon via several transport methods depending on your setup:

• Local IPC (Unix): Uses a Unix domain socket.
• Local IPC (Windows): Uses a named pipe.
• Remote: Uses WebSocket Secure (WSS).

ZeroClaw is an agent runtime written in Rust designed to be a self-hosted, personal AI assistant. It operates as a single binary that you configure and run locally on your own machine using your own API keys.

ZeroClaw's core functionality is built around three pillars:

1. Model Providers: Connects to LLMs (e.g., Anthropic, OpenAI, Ollama, and ~20 others).
2. Channels: Interfaces with the world via communication platforms like Discord, Telegram, Matrix, email, voice, webhooks, or a custom CLI.
3. Tools: Performs actions through capabilities such as shell access, web browsing, HTTP requests, hardware control, and custom MCP (Model Context Protocol) servers.

The Robot Kit provides a set of high-level tools that allow an AI agent to interact with the physical world. These tools bridge the gap between the high-level AI (Ollama) and the hardware layer.

ZeroClaw is an agent runtime that provides several core capabilities:

• Multi-channel: One agent can respond across multiple channels (Discord, Telegram, Matrix, email, webhooks, CLI, etc.).
• Provider-agnostic: Supports Anthropic, OpenAI, local Ollama, and ~20 other providers with fallback chains and routing.
• Security-first: Features supervised autonomy by default (approving medium-risk, blocking high-risk), workspace boundaries, and OS-level sandboxing (Landlock, Docker, etc.).
• Hardware-capable: Supports GPIO, I2C, SPI, and USB on devices like Raspberry Pi and ESP32 via the Peripheral trait.
• SOP Engine: Event-triggered Standard Operating Procedures (via MQTT, webhook, cron, or peripheral) with approval gates.
• ACP: Integration with IDEs/editors via the Agent Client Protocol (JSON-RPC 2.0 over stdio).

By default, ZeroClaw ships with a balanced security posture suitable for local development:

For production environments, it is recommended to increase security by enabling OTP, audit logging, and restricted tools. For pure development, you can use the YOLO mode.

ACP is ideal for scenarios where you need to manage agent sessions without the overhead of HTTP or port binding. Common use cases include:

• Editor Extensions: Implementing commands like "ask the agent about this file" directly within an IDE.
• Terminal Multiplexers: Integrating agent sessions into side panes within terminal environments.
• CI Runners: Driving an agent programmatically during continuous integration without a full gateway setup.
• Subprocess Integration: Any tool that needs to communicate with an agent via standard input/output streams.

The Agent Client Protocol (ACP) is a JSON-RPC 2.0 protocol designed to allow editors, IDEs, or other tools to drive a running ZeroClaw agent as a session host. It operates over stdio using newline-delimited JSON, making it lightweight, streamable, and easy to integrate with subprocesses.

Conceptually, it functions like the Language Server Protocol (LSP) but for agents: the host (e.g., an editor) launches the zeroclaw acp command, sends prompts via stdin, and receives session updates via stdout.

An Alias is a user-defined name assigned to a configured instance, used as a reference point to wire different parts of the configuration together.

Naming Rules (Alias Grammar)

To ensure compatibility with the configuration parser, aliases must follow these constraints:

• Use only lowercase ASCII letters, digits, and single underscores (_).
• Must start and end with a letter or a digit.
• Cannot contain double underscores (__) or hyphens (-).

Usage in Configuration

Aliases are used within section headers to identify specific instances. For example, they appear as the <alias> segment in paths like:

• [agents.<alias>]
• [providers.models.<type>.<alias>]

A Model Provider is ZeroClaw's abstraction layer for interacting with LLM (Large Language Model) endpoints. Instead of calling APIs directly, every chat-completion request is routed through a provider. This allows ZeroClaw to support various backends including remote APIs, self-hosted servers, or local instances like Ollama.

Key characteristics:

• Vendor Families: Providers are categorized by their vendor family (e.g., OpenAI, Anthropic, Ollama).
• Named Instances: You can define multiple named instances of the same vendor family (using aliases) to manage different models or configurations simultaneously.
• Configuration Path: Providers are configured under the [providers.models.<type>.<alias>] hierarchy in your configuration file.