birdxs/fastclaw repository overview

Platform admin: agents, models, skills, users, API keys

Per-agent management: chat, customize, scoped models / skills / channels / scheduler

⁠What is FastClaw?

FastClaw is an Agent Factory — it creates, manages, and runs AI agents. Each agent has its own personality (SOUL.md), memory, skills, and tools. FastClaw handles the LLM communication, tool execution, sandbox isolation, and session management.

# Install (drops the binary into ~/.local/bin and adds it to PATH)
curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash

Windows:

powershell -ExecutionPolicy Bypass -Command "iex(New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.ps1')"

⁠Quick Start

⁠1. First Run

fastclaw
# Opens setup wizard → configure LLM provider → creates default agent.
# Foreground mode; ^C to stop. Use `fastclaw daemon start` to run in
# the background, or `fastclaw daemon install` to register a
# launchd / systemd service.

⁠2. Dashboard

Open http://localhost:18953 and login with your admin token.

• Agents — Create and manage agents, each with its own personality and model
• Skills — Install shared skills from ClawHub or GitHub
• Models — Configure LLM providers (OpenAI, Anthropic, Ollama, OpenRouter, etc.)
• API Keys — Issue programmatic credentials (admin / user / agent tiers)
• Settings — General (theme), Account (profile + password), Runtime (sandbox config; admin only)

⁠3. Agent Management

Click an agent to enter its management panel:

• Chat — Talk to the agent (debug/test)
• Files — Edit SOUL.md, IDENTITY.md, MEMORY.md, etc.
• Skills — Agent-private skills
• Models — Agent-specific provider + model overrides (shadow system entries by name; agent-scope agents.defaults.model overrides the system default)
• Channels — Connect IM bots (Telegram, Discord, Slack) so end-users can chat with the agent on their platform of choice
• Scheduler — Inspect and manage cron jobs the agent created via create_cron_job ("每天 9 点提醒我", "5 分钟后叫我"); pause / delete from the UI
• Sessions — Conversation history

Sharing. Each agent has a Public access toggle in the Edit dialog (default off). When on, anyone with the chat URL — /agents/{id}/chat/ — can chat with the agent under their own account; sessions / memory / USER.md partition per chatter, while SOUL / IDENTITY / skills are shared from the owner's row. When off, only the owner (or super_admin) can access it.

⁠Architecture

~/.fastclaw/
  fastclaw.db                # SQLite default — users, agents, sessions,
                             # apikeys, configs, agent_files all live here
  skills/                    # Shared skills (bundled + installed)
  agents/
    <agentId>/agent/skills/        # Agent-private skills (filesystem only)

The database is the source of truth for everything except skill folders on disk. SQLite is the default; point FASTCLAW_STORAGE_DSN at Postgres for multi-pod deployments.

There is no fastclaw.json. Bootstrap settings (port, bind, storage DSN, sandbox backend) come from FASTCLAW_* env vars; everything user- facing (providers, channels, settings, defaults) lives in the configs table and is edited through the dashboard or fastclaw agents config.

⁠What FastClaw Stores

⁠Features

⁠LLM Providers

• OpenAI, Anthropic, Ollama, OpenRouter, Groq, DeepSeek, Mistral, and any OpenAI-compatible API
• Per-agent provider + model override (agent-scope shadows system by name)
• Prompt cache support (RawAssistant preservation)

⁠Channels

• Per-agent Telegram / Discord / Slack bot bindings — end-users chat with the agent on their platform
• Tokens validated before save (Telegram getMe, Discord /users/@me, Slack auth.test)
• Sessions are isolated per channel + chatID, so a user's Telegram thread and Discord thread stay separate

⁠Tools & Sandbox

• Built-in: exec, read_file, write_file, list_dir, web_fetch, web_search, memory_search
• E2B cloud sandbox or Docker sandbox — automatic skill + workspace hydrate, post-exec sync (sandbox-side files mirrored back to the durable store after every tool call)
• Sandbox is a boundary on hosted deploys, a tool on self-hosted installs: with FASTCLAW_DEPLOY=hosted every exec/file call is locked inside the sandbox; on a self-hosted install the host shell stays the default and the model opts into the sandbox per call with exec(sandbox:true). Set FASTCLAW_SANDBOX_ENFORCE=1 to get the hosted-style lockdown on a self-hosted install (recommended when agents are exposed to untrusted IM chatters)
• MCP server support
• Plugin system (JSON-RPC subprocess)

⁠Skills

• Bundled skills: code-runner, image-gen, data-analysis, translation, web-search, skill-creator
• Install from ClawHub⁠ or skills.sh⁠
• Agent-private or globally shared

⁠Memory

• MEMORY.md — long-term facts, auto-updated by heartbeat
• Session-based context with full history preservation
• Thinking/reasoning content preserved for memory extraction

⁠API

• OpenAI-compatible /v1/chat/completions (streaming)
• Upstream app integration contract: docs/upstream-api.md⁠
• Web chat /api/chat/stream (SSE)
• Live agent push via /api/chat/subscribe (SSE) — surfaces cron-fired and other async replies into the open chat panel without a refresh
• Session management /api/chat/sessions
• Agent CRUD /api/agents (?all=true returns the cross-tenant view, admin-only)
• Per-agent scheduler /api/agents/{id}/cron (list / toggle / delete)
• Provider management /api/config
• Skill install /api/skills/install (ClawHub + GitHub)
• API key management /api/apikeys (per-user; tiers: admin / user / agent)
• User management /api/users (admin) — top-level CRUD + nested /api/users/{id}/apikeys and /api/users/{id}/agents for admin-driven provisioning. The agents endpoint accepts forkFrom to clone an existing agent's identity (SOUL / IDENTITY / skills / model defaults) into the new user's namespace — primary building block for "user buys a bot" flows. Per-user agent_quota caps how many agents a non-admin can self-create (-1 = unlimited, 0 = admin-provisioned only).
• App-user provisioning POST /v1/users — third-party apps mint a stable fastclaw user_id per end-user, idempotent on (api_key, external_id). Or pass user on /v1/chat/completions (or X-Fastclaw-End-User header) for lazy mint on first call

⁠Configuration

Bootstrap is env-only. Everything that needs to change at runtime (providers, models, channels, defaults, sandbox toggle) lives in the database and is edited through the dashboard or fastclaw agents config.

Anything not on this list — providers, models, default model, skill catalog, channels, plugin config, scheduler — is configured at runtime through the web UI (http://localhost:18953) or the CLI (fastclaw agents config, fastclaw provider, fastclaw skill).

⁠Deployment

⁠Local

fastclaw                    # foreground (^C to stop)
fastclaw daemon start       # background (logs at ~/.fastclaw/daemon.log)
fastclaw daemon status
fastclaw daemon stop
fastclaw daemon install     # register as a launchd / systemd service

⁠Manage agents from the CLI (fastclaw agents …)

The fastclaw agents subcommand is a thin convenience wrapper around the same store the dashboard uses. Agents you create here show up in the web UI and vice-versa — there's only ever one fastclaw deployment per FASTCLAW_HOME.

# Zero to a chattable agent in one command. On a fresh install this
# creates an `admin` user (random password printed once) and starts
# the gateway daemon if it isn't already running.
fastclaw agents init alpha \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

# Set per-agent overrides (model, temperature, sandbox, …).
fastclaw agents config alpha set temperature 0.7
fastclaw agents config alpha set sandbox.enabled true

# Upload the agent's identity files.
fastclaw agents files put alpha SOUL.md ./SOUL.md
fastclaw agents files put alpha IDENTITY.md ./IDENTITY.md

# Inspect.
fastclaw agents ls
fastclaw agents config alpha get
fastclaw agents files ls alpha

# Tear down.
fastclaw agents rm alpha

The CLI opens the operator's store directly (sqlite at ~/.fastclaw/fastclaw.db, or whatever FASTCLAW_STORAGE_DSN points at) and writes through the same code paths the gateway uses. It does not require the gateway to be running — but agents init will spin one up in the background so a fresh agent is immediately reachable at http://localhost:18953. Subsequent CLI writes (config set, files put, rm, init re-runs) send SIGHUP to the running gateway so it hot-reloads without restart. Windows lacks SIGHUP delivery, so the CLI falls back to a hint asking you to run fastclaw daemon restart.

The default owner is the admin user. On an empty database agents init creates that account with a generated password (printed once); on a populated database it expects admin to exist or --username to point at an existing user.

⁠Resolving agents

CLI commands accept either a display name or an agt_… id:

• fastclaw agents config alpha get — by display name (must be unique)
• fastclaw agents config agt_d3c4a5… get — by id

If the same text matches one agent's id and a different agent's display name, the CLI reports an ambiguity instead of guessing.

When you create an agent via agents init <name>, the name is the display name and the id is auto-generated. To update an agent that was created via the dashboard, pass its id explicitly:

fastclaw agents init "Cool Agent" --id agt_d3c4a5...

⁠Configuration keys

Per-agent (saved at scope=agent under the agent's id):

• model, temperature, maxTokens, thinking, policy
• sandbox, sandbox.enabled, sandbox.backend, sandbox.image, sandbox.network

System-wide (saved at scope=system):

• plugins, plugins.<name>
• skills.install, skills.entries, skillsLearner
• tools.providers, tools.categories
• objectstore, taskqueue, heartbeat, memory, privacy, hooks, teams

Provider configs live in scope=system and are addressed as provider.<name>.<field>:

fastclaw agents config alpha set provider.openai.apiKeyEnv OPENAI_API_KEY
fastclaw agents config alpha set provider.openrouter.apiBase https://openrouter.ai/api/v1
fastclaw agents config alpha set provider.openai.model gpt-4o      # adds; idempotent
fastclaw agents config alpha set provider.openai.models '[]'        # explicit clear

Provider presets ship for openai, openrouter, anthropic, ollama, groq, deepseek, mistral — --api-key-env populates apiKey from the named environment variable, the rest comes from the preset.

⁠Agent system files

The CLI reads and writes the same agent_files table the dashboard's file editor uses. Allowlisted filenames: SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md, MEMORY.md, HEARTBEAT.md, AGENTS.md, TOOLS.md, agent.json.

⁠Manage API keys from the CLI (fastclaw apikey …)

Issue and manage programmatic credentials for external integrations.

⁠Key types

⁠Commands

# Create a key (token shown once — save immediately)
fastclaw apikey create --name "my-key" --type user [--owner <user-id>]

# List keys for a user (defaults to first super_admin)
fastclaw apikey list [--owner <user-id>]

# Delete a key
fastclaw apikey delete --id <apikey-id>

# Rotate a key (old token invalidated, new token shown once)
fastclaw apikey rotate --id <apikey-id>

Flags:

• --name (required): human-readable key name
• --type (default user): admin, user, or agent
• --owner (optional): owner user ID; defaults to first super_admin

⁠Multi-tenant app_user flow

A type=user key combined with the X-Fastclaw-End-User header enables per-end-user data isolation without pre-registering users in FastClaw:

Authorization: Bearer <user-key-token>
X-Fastclaw-End-User: <your-app-user-id>

FastClaw lazily mints a stable internal user for each unique (api_key_id, external_id) pair. Sessions, memory, and files are fully isolated per end-user.

⁠Docker

cd deploy/docker && ./start.sh

⁠Kubernetes

env:
  - name: FASTCLAW_BIND
    value: "all"
  - name: FASTCLAW_STORAGE_TYPE
    value: "postgres"
  - name: FASTCLAW_STORAGE_DSN
    valueFrom:
      secretKeyRef:
        name: fastclaw-db
        key: dsn
  - name: FASTCLAW_OBJECT_STORE_ENDPOINT
    value: "s3.amazonaws.com"
  - name: FASTCLAW_OBJECT_STORE_BUCKET
    value: "fastclaw-skills"

No config file is mounted — bootstrap is env-only. See deploy/k8s/ for full manifests.

⁠Building

make build                  # builds the web bundle and the Go binary → bin/fastclaw
make install                # installs to $HOME/.local/bin (override with PREFIX=)
make release-local          # cross-compile darwin / linux / windows into dist/

The Makefile bakes the version, commit, and build date into the binary via -ldflags. CI uses these targets too — see .github/workflows/.

⁠License

FastClaw is source-available under the FastClaw Community License⁠, based on Apache License 2.0 with additional conditions.

TL;DR:

• ✅ Use it commercially as a backend for your own product
• ✅ Internal deployment within your organization
• ❌ Hosting FastClaw as a multi-tenant SaaS for unrelated organizations (without a commercial license)
• ❌ Removing or modifying the FastClaw branding in the dashboard UI

The full Apache 2.0 text is reproduced inside the LICENSE⁠ file under the addendum. For commercial licensing inquiries: [email protected]⁠.