Intent into action
Use an agent planning loop and registered tools to move from a request to an executable task.
Build with your own models, tools and channels. Inspect every boundary. Keep the operating context where you choose.
# 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
Isolation, audit and access controls are part of the runtime architecture.
Run hosted and local providers behind a single model abstraction.
Connect backends, skills and messaging channels as your setup grows.
Practical notes grounded in the repository. Start with the CLI, then look closely at the architecture, security boundaries and extensions.
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.
Use an agent planning loop and registered tools to move from a request to an executable task.
Configure authentication, execution sandboxes, approval flows, and audit records.
Persist sessions in SQLite with FTS5 full-text indexing for retrieval.
Work through the CLI, API gateway, web dashboard, or supported channel adapters.
Features and implementation references are described in the source feature matrix. Capabilities depend on your configuration and runtime environment.
Install with Python 3.11 or newer. The repository recommends uv for dependency management, and Linux for its Landlock filesystem controls.
git clone https://github.com/krishujeniya/AmberClaw.git
cd AmberClaw
cp .env.example .env
uv syncuv run amberclaw doctor
uv run amberclaw agentFor the FastAPI gateway and its web dashboard, bind to the local interface while developing:
uv run uvicorn amberclaw.api.main:app --host 127.0.0.1 --port 8000Open http://127.0.0.1:8000 to reach the local web dashboard. Review access controls before making it reachable outside your machine.
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.
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:11434Values 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.
AmberClaw documents a decoupled asynchronous kernel. The message bus connects interfaces to planning, state, execution backends, and human oversight.
The repository describes layered controls: Linux filesystem confinement, credential redaction, authenticated API access, approval tickets, and SHA-256 hash-chained audit logs.
Restrict filesystem access within permitted workspace boundaries on supported Linux kernels.
Append-only JSONL audit events support tamper detection during review.
Bearer JWT, API keys, middleware rate limits, and production CORS controls are documented.
Route sensitive operations to a human before execution when policy requires it.
“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.
The documented LiteLLM abstraction supports capability-aware routing across hosted and local providers, including OpenAI, Anthropic, Ollama, and vLLM.
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.
The source feature matrix lists nine backend implementations. Each has different dependency, isolation, and account requirements.
| Backend | Execution context |
|---|---|
| Local | Local subprocesses, with Landlock where supported |
| Docker | Containerized execution |
| SSH | Remote shell execution |
| Daytona | Cloud development workspaces |
| Singularity | HPC container workloads |
| Modal | Serverless containers |
| Vercel | Cloud execution integration |
| WASM | Wasmtime fuel-bounded execution |
| E2B | MicroVM-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.
SessionDB uses SQLite with WAL journaling and FTS5 indexing. The platform also documents multi-scope memory, persistent agent profiles, and memory deletion interfaces.
Search prior sessions with FTS5 rather than depending on the current context window alone.
Use documented session and deletion APIs to manage conversation records.
AmberClaw connects agent interactions with messaging platforms and enterprise communication integrations. Each channel requires its own credentials and provider-specific configuration.
Channel implementations are listed in the feature matrix. Validate webhook, network, and SDK requirements for your chosen integration.
FastAPI endpoints expose chat, server-sent token streams, agent profiles, session management, approval tickets, and telemetry. Protected routes require authentication.
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"}'| Endpoint | Purpose |
|---|---|
| POST /api/v1/auth/token | Issue an authentication token |
| GET /api/v1/auth/me | Inspect the authenticated principal |
| POST /api/v1/chat | Chat completion |
| POST /api/v1/chat/stream | Server-Sent Events (SSE) |
| GET /api/v1/agents | List agent profiles |
| GET /api/v1/memory/sessions | List sessions |
| GET /api/v1/tickets/pending | Pending human approvals |
| GET /metrics | Prometheus metrics |
| GET /health | Health probe |
The repository documents SSE event kinds token, thought, tool_call, done and error. Avoid exposing sensitive stream data to unauthorized users.
Tools are registered in Python using Pydantic input schemas. Skill bundles combine instruction manifests with executable tool definitions, subject to runtime security policies.
my_skill/
├── SKILL.md
└── main.py---
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.
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.
ollama pull llama3.1
ollama pull mxbai-embed-large{
"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 ↗
The repository contains Docker Compose configurations and runbooks covering incident response, backup, provider outages, and production operations.
# 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 -dReview 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.
Run the built-in doctor command first. These common failures appear in the repository's troubleshooting and local deployment guides.
Check the correct provider key, selected model, base URL, and upstream rate limits. Keep secrets in local configuration, not in logs or public issues.
Bind Uvicorn to an available port. Examples in the source documentation use different ports for different deployment paths.
Verify that Ollama is serving on the configured base URL, inspect ollama ps, and select a model suitable for your hardware.
Verify provider credentials, SDK requirements, webhooks, and firewall rules. The WhatsApp bridge has a documented Node.js dependency.
Run uv run pytest in your workspace and check the relevant GitHub Actions run. Historical README test counts do not verify a fresh installation.
Read the source, understand the boundaries and contribute a fix or a new capability. The repository holds the implementation details.