Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

AsterClaw

AsterClaw is a lightweight Rust AI agent with a local gateway, tool execution, and channel integrations.

This documentation includes:

  • user setup and runtime basics
  • architecture overview
  • CLI and configuration reference
  • security and operations practices
  • profiling scripts
  • GitHub Pages publishing flow
  • developer workflow and extension guidance

Quick Start

Requirements

  • Rust (stable)
  • cargo
  • Git
  • optional: mdbook

Build

cargo build --release

Initialize

asterclaw onboard

Run gateway

asterclaw gateway

Check status

asterclaw status

Preview docs locally

mdbook serve docs

CLI Reference

Based on src/main.rs.

Core commands

asterclaw onboard
asterclaw agent [-m|--message <text>] [-s|--session <key>]
asterclaw gateway [--debug]
asterclaw status
asterclaw version

Global flags

  • -d, --debug (global): asterclaw --debug <command>
  • gateway --debug is parsed, but currently adds no separate behavior beyond global --debug

Cron

asterclaw cron list [--enabled-only]
asterclaw cron add --name <name> --message <text> [--every <sec> | --cron <expr>] [--channel <name>] [--chat-id <id>] [--enabled true|false]
asterclaw cron remove <id>
asterclaw cron enable <id>
asterclaw cron disable <id>

Auth

asterclaw auth login [--provider <name>] [--token <token>] [--device-code]
asterclaw auth logout [--provider <name>]
asterclaw auth status

Skills

asterclaw skills list
asterclaw skills install <owner/repo/path>
asterclaw skills remove <name>
asterclaw skills search
asterclaw skills show <name>

Migrate

asterclaw migrate [--dry-run] [--config-only] [--workspace-only] [--force]

Architecture

Core modules:

  • main.rs — CLI and runtime bootstrap
  • agent.rs — agent loop and tool-call orchestration
  • tools/* — tool implementations
  • channels.rs — channel adapters
  • providers/* — LLM provider adapters
  • health.rs — /health and /ready

Request flow:

  1. inbound message is received
  2. context is built
  3. model may call tools
  4. tool results are returned to model context
  5. final response is emitted and session is persisted

Configuration

Current source of truth: src/config.rs.

Config locations

  • primary: ~/.asterclaw/config.json
  • legacy fallback: ~/.picoclaw/config.json
  • if ASTERCLAW_HOME is set, path resolves to ASTERCLAW_HOME/config.json

Template:

  • config/config.example.json

Top-level sections

  • agents
  • channels
  • providers
  • gateway
  • runtime
  • tools
  • heartbeat
  • devices

agents.defaults

  • workspace
  • restrict_to_workspace
  • provider
  • model
  • max_tokens
  • temperature
  • max_tool_iterations

channels.telegram

  • enabled
  • token
  • proxy
  • allow_from

When Telegram is enabled, token and non-empty allow_from are required.

providers

Sections present in Config schema:

  • openai, openrouter, groq, zhipu, gemini, deepseek, anthropic

Providers actually implemented in runtime (src/providers/mod.rs):

  • openai, openrouter, groq, zhipu (glm), deepseek

Important:

  • anthropic/claude is explicitly rejected in current MVP
  • gemini exists in config schema, but provider runtime support is not implemented yet

Fields per provider section:

  • api_key, api_base, proxy, auth_method, connect_mode

API keys can be provided via config or env:

  • OPENAI_API_KEY
  • OPENROUTER_API_KEY
  • GROQ_API_KEY
  • ZHIPU_API_KEY
  • DEEPSEEK_API_KEY

gateway

  • host
  • port

runtime

  • worker_threads
  • max_blocking_threads

Low-memory baseline:

  • worker_threads: 1
  • max_blocking_threads: 8..16

tools.web

  • brave.*
  • duckduckgo.*
  • fetch_default_max_chars
  • fetch_hard_max_chars
  • fetch_hard_max_bytes

For Brave, API key is taken from tools.web.brave.api_key or BRAVE_API_KEY.

tools.exec

  • confirm_unknown
  • auto_allow_prefixes
  • require_confirm_prefixes
  • always_deny_prefixes
  • stdout_max_bytes
  • stderr_max_bytes

tools.tool_output_max_chars

  • 0 means no truncation
  • >0 applies truncation in tool loop context

Tools

Registered in ToolRegistry::register_builtin_tools() (src/tools/mod.rs).

Filesystem

  • read_file
  • write_file
  • edit_file
  • append_file
  • list_dir

Shell

  • exec

Includes policy checks and output limits. Exec command timeout is 30 seconds.

Web

  • web_search
  • web_fetch

Includes SSRF guard and configurable response bounds. web_search clamps count to 1..10.

Messaging and orchestration

  • message
  • spawn
  • subagent

Scheduling and memory

  • cron
  • memory (read, write, append, read_daily, append_daily)

Tool-output context limit

  • tools.tool_output_max_chars limits what tool responses are sent back into LLM context
  • 0 disables truncation

Device

  • i2c
  • spi

On non-Linux hosts, device operations may fail at runtime by design.

Security

Telegram

When channels.telegram.enabled=true:

  • token is required
  • non-empty allow_from is required

Use private chat + allow-list mode in production.

Exec policy

Command classes:

  • auto-allow
  • require-confirm
  • always-deny

Recommended baseline:

  • keep confirm_unknown = true
  • keep auto_allow_prefixes minimal
  • avoid weakening always_deny_prefixes

Web protection

  • web_fetch blocks local/private targets (SSRF guard)
  • keep tools.web.fetch_* bounds in place

Secret management

  • do not commit real API keys
  • keep secrets in local config or CI secret store

Operations

Start gateway

asterclaw gateway

Health endpoints

  • GET /health
  • GET /ready

Common operational commands

asterclaw status
asterclaw cron list
asterclaw auth status
asterclaw skills list

Restart gateway after editing ~/.asterclaw/config.json.

For verbose logs, use asterclaw --debug gateway. asterclaw gateway --debug is currently equivalent to normal gateway run (without global debug).

Profiling and NFR

Scripts are available in scripts/.

Baseline

pwsh scripts/nfr_baseline.ps1

Comparison harness

pwsh scripts/nfr-harness.ps1

Tool-focused sampling

pwsh scripts/simply-profile.ps1

Use identical scenarios before/after changes for valid comparisons.

GitHub Pages Deployment

Build locally:

mdbook build docs

The HTML output is generated in docs/book.

Workflow file:

  • .github/workflows/docs-pages.yml

Repository setup:

  1. Settings -> Pages
  2. Build and deployment -> Source: GitHub Actions
  3. Ensure branch target in workflow matches your default branch

Before first deploy, update:

  • docs/book.toml -> git-repository-url
  • docs/book.toml -> edit-url-template

Developer Guide

Project layout

  • src/main.rs — CLI bootstrap
  • src/agent.rs — agent loop
  • src/tools/ — tools
  • src/channels.rs — channel adapters
  • src/providers/ — provider adapters
  • src/config.rs — config schema
  • tests/ — e2e tests
  • scripts/ — profiling/NFR scripts

Local workflow

cargo check
cargo fmt
cargo clippy -- -D warnings
cargo test

Adding a tool

  1. create a module in src/tools/
  2. implement Tool trait
  3. export and register it in src/tools/mod.rs
  4. add tests for success/error/edge cases
  5. update docs in docs/src, docs/src/en, docs/src/pt-br

Keeping docs aligned with code

  • CLI: cargo run -- --help, cargo run -- <subcommand> --help
  • Config: src/config.rs and config/config.example.json
  • Tools: src/tools/mod.rs and src/tools/*.rs
  • Docs build check: mdbook build docs