amberclaw.Documentation
The self-hosted agent runtime

Intelligence,
under your control.

Build with your own models, tools and channels. Inspect every boundary. Keep the operating context where you choose.

Python 3.11+Open source · MITLocal & cloud runtimes
bash · getting started
# Start from the source.
$ git clone \
  https://github.com/krishujeniya/AmberClaw.git
$ cd AmberClaw
$ cp .env.example .env
$ uv sync
$ uv run amberclaw doctor

# Start the local agent.
$ uv run amberclaw agent
YOUR WORKSPACE · YOUR CONFIGURATION
Private by design

Isolation, audit and access controls are part of the runtime architecture.

Flexible model routing

Run hosted and local providers behind a single model abstraction.

Extensible execution

Connect backends, skills and messaging channels as your setup grows.

Developer handbook · 2026.0.1

The field guide.

Practical notes grounded in the repository. Start with the CLI, then look closely at the architecture, security boundaries and extensions.

No matching sections. Try a different search or clear the field.

A runtime you can inspect.

AmberClaw is an open, self-hosted AI agent runtime for teams and individuals. It brings model routing, messaging channels, tool execution, memory, and operational controls into a Python-based system.

01 / PLAN

Intent into action

Use an agent planning loop and registered tools to move from a request to an executable task.

02 / CONTROL

Boundaries first

Configure authentication, execution sandboxes, approval flows, and audit records.

03 / REMEMBER

Durable context

Persist sessions in SQLite with FTS5 full-text indexing for retrieval.

04 / CONNECT

One runtime, many entrances

Work through the CLI, API gateway, web dashboard, or supported channel adapters.

Documentation is grounded in the repository.

Features and implementation references are described in the source feature matrix. Capabilities depend on your configuration and runtime environment.

Your first five minutes.

Install with Python 3.11 or newer. The repository recommends uv for dependency management, and Linux for its Landlock filesystem controls.

Install AmberClaw

terminal · bash
git clone https://github.com/krishujeniya/AmberClaw.git
cd AmberClaw
cp .env.example .env
uv sync

Check the environment

terminal · bash
uv run amberclaw doctor
uv run amberclaw agent

For the FastAPI gateway and its web dashboard, bind to the local interface while developing:

terminal · bash
uv run uvicorn amberclaw.api.main:app   --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 to reach the local web dashboard. Review access controls before making it reachable outside your machine.

Full setup documentation ↗

Configure what matters.

Start from .env.example. Supply credentials for at least one provider, keep your secrets out of version control, and verify settings with the doctor command.

example · .env (illustrative values)
AMBERCLAW_ENV=development
AMBERCLAW_WORKSPACE_DIR=./data/workspace
AMBERCLAW_SECRET_KEY=replace-with-a-private-secret
AMBERCLAW_AUTH_ENABLED=true
AMBERCLAW_RATE_LIMIT=10

# Configure a provider:
# OPENAI_API_KEY=...
# ANTHROPIC_API_KEY=...
# OLLAMA_API_BASE=http://localhost:11434
Handle keys as secrets.

Values above are examples, not deployable credentials. Verify the actual supported configuration keys in .env.example.

Use uv run amberclaw onboard for guided onboarding and uv run amberclaw doctor to inspect dependencies, workspace paths, and provider configuration.

Follow a message through the system.

AmberClaw documents a decoupled asynchronous kernel. The message bus connects interfaces to planning, state, execution backends, and human oversight.

REFERENCE TOPOLOGY
Messaging channels · API gateway · CLI
Asynchronous message bus
Agent planning · LiteLLM · SessionDB
Approval · isolation · audit · tool execution

Separation of responsibilities

  • Interfaces receive inputs from chat channels, the CLI, and HTTP endpoints.
  • Planning and routing select model calls and tools.
  • State stores searchable session history and agent profiles.
  • Execution selects a backend through the terminal factory.
  • Governance records activity and requests approval for high-risk actions.

Architecture deep dive ↗

Trust is a configured boundary.

The repository describes layered controls: Linux filesystem confinement, credential redaction, authenticated API access, approval tickets, and SHA-256 hash-chained audit logs.

FILESYSTEM

Landlock LSM

Restrict filesystem access within permitted workspace boundaries on supported Linux kernels.

TRACEABILITY

Hash-chained logs

Append-only JSONL audit events support tamper detection during review.

API

Authentication

Bearer JWT, API keys, middleware rate limits, and production CORS controls are documented.

GOVERNANCE

Approval queue

Route sensitive operations to a human before execution when policy requires it.

Important security limitation

“Zero-trust” is the project's architectural description. This page does not assert independent certification, audited compliance, or security across every deployment. Backend and OS choices affect the available protections.

Security policy ↗

Bring the model you need.

The documented LiteLLM abstraction supports capability-aware routing across hosted and local providers, including OpenAI, Anthropic, Ollama, and vLLM.

OpenAIAnthropicOllamavLLMLiteLLM

Configure credentials or base URLs for your provider, then check model availability and local dependency requirements. Provider availability and costs belong to the providers, not to this documentation site.

Execution in the right place.

The source feature matrix lists nine backend implementations. Each has different dependency, isolation, and account requirements.

BackendExecution context
LocalLocal subprocesses, with Landlock where supported
DockerContainerized execution
SSHRemote shell execution
DaytonaCloud development workspaces
SingularityHPC container workloads
ModalServerless containers
VercelCloud execution integration
WASMWasmtime fuel-bounded execution
E2BMicroVM-backed tasks

The factory is referenced at src/amberclaw/terminal/factory.py. The presence of a backend does not guarantee its optional dependencies are installed.

Keep the thread.

SessionDB uses SQLite with WAL journaling and FTS5 indexing. The platform also documents multi-scope memory, persistent agent profiles, and memory deletion interfaces.

LOOKUP

Indexed context

Search prior sessions with FTS5 rather than depending on the current context window alone.

LIFECYCLE

Persistent and removable

Use documented session and deletion APIs to manage conversation records.

Work across channels.

AmberClaw connects agent interactions with messaging platforms and enterprise communication integrations. Each channel requires its own credentials and provider-specific configuration.

TelegramDiscordMatrixEmailFeishu / LarkDingTalkMoChatWhatsAppSlack

Channel implementations are listed in the feature matrix. Validate webhook, network, and SDK requirements for your chosen integration.

A gateway for your tools.

FastAPI endpoints expose chat, server-sent token streams, agent profiles, session management, approval tickets, and telemetry. Protected routes require authentication.

example · authenticated request
curl -X POST http://127.0.0.1:8000/api/v1/chat   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"message":"Analyze system load","model":"gpt-4o"}'
EndpointPurpose
POST /api/v1/auth/tokenIssue an authentication token
GET /api/v1/auth/meInspect the authenticated principal
POST /api/v1/chatChat completion
POST /api/v1/chat/streamServer-Sent Events (SSE)
GET /api/v1/agentsList agent profiles
GET /api/v1/memory/sessionsList sessions
GET /api/v1/tickets/pendingPending human approvals
GET /metricsPrometheus metrics
GET /healthHealth probe

The repository documents SSE event kinds token, thought, tool_call, done and error. Avoid exposing sensitive stream data to unauthorized users.

Full API reference ↗

Teach the runtime a new skill.

Tools are registered in Python using Pydantic input schemas. Skill bundles combine instruction manifests with executable tool definitions, subject to runtime security policies.

example · skill structure
my_skill/
├── SKILL.md
└── main.py
example · SKILL.md
---
name: web_researcher
version: 1.0.0
description: Approved-source search and summarization.
capabilities:
  - network_egress
  - filesystem_read
---

# Web Researcher Skill
Fetch approved sources and return concise summaries.

Review the tool registry, policy enforcement, and the skill creation guide ↗. Manifest metadata alone is not a security boundary.

Keep inference local.

The repository's offline-first guide uses Ollama with model names in a LiteLLM-compatible provider configuration. Download required weights while online before moving to an isolated environment.

terminal · bash
ollama pull llama3.1
ollama pull mxbai-embed-large
example · ~/.amberclaw/config.json
{
  "agents": {
    "defaults": {
      "model": "ollama/llama3.1",
      "embedding_model": "ollama/mxbai-embed-large"
    }
  },
  "providers": {
    "ollama": {
      "api_base": "http://localhost:11434"
    }
  }
}

Check memory and VRAM before choosing a local model. Local deployment guide ↗

From laptop to deployment.

The repository contains Docker Compose configurations and runbooks covering incident response, backup, provider outages, and production operations.

documented compose commands
# Production stack
docker compose -f deploy/docker/docker-compose.prod.yml up -d

# Air-gapped internal-network stack
docker compose -f deploy/docker/docker-compose.airgapped.yml up -d

Review service images, volume mounts, exposed ports, secrets, and required dependencies before deploying. The offline Compose path is documented as an internal-network stack; verify its actual network configuration for your environment.

Audit logsPrometheusOperational runbooksDocker Compose

Diagnose before you change.

Run the built-in doctor command first. These common failures appear in the repository's troubleshooting and local deployment guides.

My provider request fails.

Check the correct provider key, selected model, base URL, and upstream rate limits. Keep secrets in local configuration, not in logs or public issues.

The gateway says its port is in use.

Bind Uvicorn to an available port. Examples in the source documentation use different ports for different deployment paths.

Ollama refuses the connection or runs slowly.

Verify that Ollama is serving on the configured base URL, inspect ollama ps, and select a model suitable for your hardware.

A messaging integration won't connect.

Verify provider credentials, SDK requirements, webhooks, and firewall rules. The WhatsApp bridge has a documented Node.js dependency.

How do I verify the project?

Run uv run pytest in your workspace and check the relevant GitHub Actions run. Historical README test counts do not verify a fresh installation.

Troubleshooting notes ↗ · Open an issue ↗

Keep building

Make the runtime yours.

Read the source, understand the boundaries and contribute a fix or a new capability. The repository holds the implementation details.

Explore the repository
Copied