AA Claw 🦀

Lightweight AI Agent gateway in Rust — chat, memory, remote control, and task orchestration in a single static binary. Auth via aaclaw.net.

What is AA Claw?

One command that gives you:

• 🪶 A lightweight agent — single ~17MB Rust binary, statically linked with musl; zero glibc dependency, no runtime to install
• 🔌 Any OpenAI-compatible API — DeepSeek / OpenRouter / OpenAI / local ollama; switch by changing one config line
• 🧠 Persistent memory — store facts, search them semantically, auto-consolidate overnight
• 🎮 Remote control — turn any server into a web-controlled agent
• 🧩 Task orchestration — describe a goal, get it decomposed and executed as subtasks
• 💬 Sessions — every conversation is saved and resumable

This guide walks you through everything, step by step. No prior setup assumed.

Requirements

• Linux x64 (musl static build — works on any distro, from Alpine to Ubuntu)
• Node >= 16 (only for the npm installer; the binary itself has zero dependencies)
• An API key from any OpenAI-compatible provider (DeepSeek, OpenRouter, OpenAI, ollama...)

Install

npm install -g aaclaw

Verify it works:

aaclaw --version

npm update -g aaclaw      # upgrade later
npm uninstall -g aaclaw   # remove

If the platform package was skipped: npm install -g aaclaw --include=optional

Step 1 — Log in

AA Claw authenticates through aaclaw.net. Two ways:

Option A: browser OAuth (easiest on a desktop)

aaclaw login

Choose option 1, confirm on the authorization page, copy the token — done.

Option B: paste a token (headless servers, SSH, containers)

1. Register at aaclaw.net
2. Open the /tokens page and generate an API token (looks like tk_xxxxxxxx)
3. Paste it into the terminal:

aaclaw login tk_xxxxxxxx

Check you're authenticated:

aaclaw whoami

Tokens are valid for 30 days and cached in ~/.aaclaw/auth.json. Re-run aaclaw login to refresh, aaclaw logout to clear.

Step 2 — Connect your AI provider

Create a config file in your working directory:

aaclaw init

Then edit aaclaw.toml with your provider of choice:

[[providers]]
name = "deepseek"
type = "openai"
api_key = "sk-..."
default_model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"

Any OpenAI-compatible endpoint works. Common choices:

| Provider | base_url | default_model example | |------|------|------| | DeepSeek | https://api.deepseek.com/v1 | deepseek-chat | | OpenRouter | https://openrouter.ai/api/v1 | any model slug | | OpenAI | https://api.openai.com/v1 | gpt-4o-mini | | ollama (local) | http://localhost:11434/v1 | llama3 |

Inspect what AA Claw loaded:

aaclaw config

Step 3 — Start talking

One-shot question:

aaclaw ask "explain musl vs glibc in two sentences"

Interactive chat:

aaclaw

Inside chat you can use tools (shell, file, http, git, web_search) — the agent executes and reports back. Exit with Ctrl+C.

Congratulations — that's the basic loop. The rest of this guide covers what makes AA Claw more than a chat wrapper.

Feature walkthrough

💾 Memory — teach it facts, recall them later

aaclaw remember "our staging server is 10.0.0.42, prod is 10.0.0.51"
aaclaw memory "staging server address"

memory does semantic search — you don't need exact keywords.

Over time, run:

aaclaw dream

Auto-Dream consolidates accumulated memories: merges duplicates, prunes noise, keeps the important stuff compact.

💬 Sessions — nothing is lost

Every conversation is persisted. List them:

aaclaw sessions

Resume the latest, or a specific one:

aaclaw resume            # latest session
aaclaw resume <id>       # specific session

🌐 Remote control — drive a server from the web

Turn the CLI into an agent controlled from aaclaw.net:

aaclaw remote                      # shows up as your hostname
aaclaw remote --name build-box     # custom name

Events stream back live; you send commands from the browser. Ideal for headless boxes, CI runners, or keeping an agent on a VPS.

To expose channels (web UI and more) as a daemon:

aaclaw serve                       # default listen address from config
aaclaw serve --web 0.0.0.0:8080    # override

🧩 Orchestrate — one goal, many subtasks

Give it a complex goal; it decomposes, executes, and reports:

aaclaw orchestrate "write a crawler for example.com, test it, and save results to csv"

Use this when a task naturally has stages (build → test → package, scrape → clean → store). For single questions, ask is faster.

🛠️ Self-optimization loop

Point the Meta-Harness at a codebase:

aaclaw optimize

It generates tests, tracks coverage across runs, and flags regressions. Best run repeatedly in a project directory under version control.

🎯 Skills

aaclaw skills                  # scan data/skills/
aaclaw skills --dir my/skills  # custom directory

Drops skill files in a directory and the pipeline picks them up. See aaclaw skills --help for matching options.

Command reference

| Command | What it does | |------|------| | chat | Interactive chat (default when no command given) | | ask <prompt> | Single one-shot prompt | | serve | Start web server + all enabled channels (daemon mode) | | remote | Run as a remote-controlled agent; commands come from aaclaw.net | | login [token] / logout / whoami | Auth: login (browser OAuth or tk_... token) / logout / status | | sessions / resume [id] | List sessions / resume (latest if no ID given) | | remember <text> / memory <query> | Store a memory / semantic search | | dream | Auto-Dream memory consolidation | | orchestrate <prompt> | Decompose and execute a complex task | | optimize | Meta-Harness loop: tests / coverage / regression detection | | skills | Test the skills pipeline | | feedback <text> | Send bugs or ideas straight to the team (first line = subject) | | init / config | Initialize config file / show current config | | status | Version and system info |

Global option: -c, --config <FILE> to use a different config (default aaclaw.toml).

Configuration

aaclaw.toml is loaded from the current directory (see aaclaw init / aaclaw config). Multiple [[providers]] blocks are allowed; the agent picks by priority.

Platform Support

| Platform | Status | |------|------| | linux-x64 (musl static) | ✅ v0.3.0+ | | linux-arm64 / darwin / win32 | 🚧 future releases |

Feedback & Links

• Found a bug or have an idea? aaclaw feedback "your message here" — it lands directly in our inbox
• 🌐 Website / auth service: aaclaw.net
• 📦 npm package: npmjs.com/package/aaclaw

License

Copyright © 2026 Theone-best — Proprietary software. All rights reserved. Licensed for installation and use in binary form only; redistribution, reverse engineering, or removal of copyright notices is prohibited. See LICENSE for the full terms. Installing or using the software means you accept the agreement.