# PersonalClaw > A self-hosted personal AI agent — an agentic operating system for one person. > Chat, autonomous goal loops, long-term memory, a knowledge base, skills, scheduled > automation and channel integrations, behind one gateway process and one web > dashboard you own. Local-first, provider-agnostic, zero telemetry, MIT. Documentation below describes PersonalClaw v0.2.2 exactly — it is generated from the tagged source, not written separately. PersonalClaw sends no telemetry: there is no adoption instrumentation in the product or on this site. ## Install ``` uv tool install --python 3.13 personalclaw && personalclaw gateway ``` ## Documentation - [Documentation](https://personalclaw.dev/docs): This documentation is generated from the tagged PersonalClaw release this site publishes, not written alongside it — so it describes the version you can actually install. ## Guides Task-oriented walkthroughs: install, first run, containers, remote access. - [Guides](https://personalclaw.dev/docs/guides): The guides walk through running PersonalClaw: installing it, getting a first conversation working, and the specific setups that come up early. - [Automations you can leave alone](https://personalclaw.dev/docs/guides/automations): An automation is only useful if you can stop watching it. - [Build a channel app](https://personalclaw.dev/docs/guides/build-a-channel-app): A channel is a place a person talks to their assistant that is not the dashboard: a chat app, a DM, a mailbox. - [Working inside a chat](https://personalclaw.dev/docs/guides/chat-surface): Most of what PersonalClaw does happens in one long conversation, and a long conversation needs more than a send button. - [Companion apps on your local network](https://personalclaw.dev/docs/guides/companion-apps): A companion app is a phone or a second computer driving your gateway — the same dashboard, rendered on a different screen. - [Running PersonalClaw in containers](https://personalclaw.dev/docs/guides/containers): The published Docker images are a projection of the same release artifact as every other install path — the gateway image bundles the wheel (with the prebuilt dashboard) and the web image bundles the SPA behind an… - [The desktop app](https://personalclaw.dev/docs/guides/desktop): PersonalClaw's desktop shell is a thin Electron wrapper around the same gateway and dashboard you get in a browser. - [Getting started](https://personalclaw.dev/docs/guides/getting-started): PersonalClaw is a self-hosted personal AI agent: a local gateway process that serves a web dashboard, runs agents with tools/memory/skills, and connects to channels. - [Platforms](https://personalclaw.dev/docs/guides/platforms): Where PersonalClaw runs and what to know per platform. - [Reaching your dashboard from outside your home network](https://personalclaw.dev/docs/guides/remote-access): By default PersonalClaw is a local program: it binds to your machine, and you get in with a token link (personalclaw token). - [Writing skills](https://personalclaw.dev/docs/guides/skills): A skill is a directory with a SKILL.md in it: a procedure you want the agent to follow the same way every time, stored as markdown instead of retyped into a prompt. - [Using PersonalClaw from your editor](https://personalclaw.dev/docs/guides/use-from-your-ide): Your editor's assistant already has an MCP client in it. - [When PersonalClaw is not the right tool (yet)](https://personalclaw.dev/docs/guides/when-not-to-use-personalclaw): Most projects tell you what they do. - [Authoring workflow templates](https://personalclaw.dev/docs/guides/workflow-templates): A template is a reusable workflow spec: a tree of typed nodes plus declared inputs and metadata. ## Reference Exact surfaces: CLI commands, configuration keys, the HTTP API, file formats. - [Reference](https://personalclaw.dev/docs/reference): Reference is the exact-surface section: the command-line interface, every configuration key, and the HTTP API the gateway serves. - [Config reference — operator knobs (~/.personalclaw/config.json)](https://personalclaw.dev/docs/reference/config-reference): Most settings live in the dashboard (Settings → …). - [API overview](https://personalclaw.dev/docs/reference/api-overview): The gateway serves a REST + WebSocket API on the dashboard port (default 10000). - [HTTP route reference](https://personalclaw.dev/docs/reference/api-routes): Every HTTP route the gateway registers: 930 registrations over 755 distinct paths — 923 agent-callable (/api/, non-websocket) and 7 websocket or internal. - [CLI reference](https://personalclaw.dev/docs/reference/cli): The personalclaw command is the single entry point (installed by pip install -e . via the personalclaw console script; source: src/personalclaw/cli.py). - [Configuration reference](https://personalclaw.dev/docs/reference/configuration): PersonalClaw's core configuration lives in one JSON file: ~/.personalclaw/config.json (the directory can be relocated with the PERSONALCLAW_HOME environment variable). - [SKILL.md format reference](https://personalclaw.dev/docs/reference/skill-format): PersonalClaw reads the same SKILL.md files the wider agent-skill ecosystem writes. ## Architecture How the parts fit: the gateway, providers, memory and knowledge, loops, apps. - [Architecture](https://personalclaw.dev/docs/architecture): Architecture explains how PersonalClaw is put together: the gateway process, the provider boundary, memory and knowledge, loops, tasks and triggers, and the app platform. - [AgentActivityFeed: the agent-worlds read contract](https://personalclaw.dev/docs/architecture/agent-activity-feed): An agent world is an ambient scene of what your agents are doing right now — a thing you glance at, not a list you read. - [The App Platform](https://personalclaw.dev/docs/architecture/app-platform): Apps are how PersonalClaw grows capabilities without core edits: model providers, channels, agents, search engines, tools, and full backend+UI dashboards are all apps. - [Chat & Sessions](https://personalclaw.dev/docs/architecture/chat-sessions): How a message becomes a turn: the session model, the dashboard chat pipeline, persistence, and the memory-privacy modes. - [Inbox & Channels](https://personalclaw.dev/docs/architecture/inbox-channels): Two seams connect PersonalClaw to the outside conversational world: the inbox (things arriving for the user's attention) and channels (bidirectional messaging surfaces like Slack — implemented entirely by apps… - [Knowledge & Memory](https://personalclaw.dev/docs/architecture/knowledge-memory): Two related but distinct subsystems: Knowledge is the user's ingested content library (notes, documents, media) with a processing pipeline and hybrid search; Memory is what the assistant learns and recalls across… - [Loops — the Autonomous Work Engine](https://personalclaw.dev/docs/architecture/loops): A loop is a long-running autonomous work unit: a worker agent iterates in cycles toward a goal while a supervisor judges progress against ground truth. - [MCP end-user identity propagation without raw-token passthrough — design note](https://personalclaw.dev/docs/architecture/mcp-end-user-identity): This note answers one question: how does a shared MCP server learn which end user a request is for, when the MCP authorization spec forbids forwarding the end user's raw token? It exists because the ecosystem… - [PersonalClaw — Architecture Overview](https://personalclaw.dev/docs/architecture/overview): PersonalClaw is a self-hosted personal AI gateway: one long-running process that hosts chat sessions, autonomous loops, a knowledge base, memory, tasks, scheduling, an inbox, and an app platform — all behind a local… - [The Provider Boundary — What Belongs in Core, and Why](https://personalclaw.dev/docs/architecture/provider-boundary): PersonalClaw's central architectural tenet: the core package is provider-agnostic. - [Security Model](https://personalclaw.dev/docs/architecture/security): Defense in depth for a system that runs an autonomous agent on your machine: authentication modes, command screening, an OS sandbox, one egress chokepoint, scoped tokens, supply-chain gates, untrusted-content… - [Shared-Store Provider Conformance](https://personalclaw.dev/docs/architecture/shared-store-provider-conformance): A shared-store provider is any provider that serves records some of which were attributed to somebody other than the local owner: a multi-tenant task backend, a trigger store (the bundled shared-automations app), a… - [SSO / OIDC integration — design note](https://personalclaw.dev/docs/architecture/sso-oidc-integration): Read security.md §"Auth modes" first. - [Tasks, Triggers & Workflows](https://personalclaw.dev/docs/architecture/tasks-triggers): The "get things done" layer: a task hierarchy shared by chat and the UI, cron/event triggers with pluggable actions, and SOP-style workflows. - [Tool-name wire fidelity](https://personalclaw.dev/docs/architecture/tool-name-wire): What happens to a tool's name between its ToolDefinition and the moment the runtime dispatches a call back to it. - [Tool-schema wire fidelity](https://personalclaw.dev/docs/architecture/tool-schema-wire): What happens to a tool's parameter schema and description between its ToolDefinition and the model provider. - [Widgets: the child→parent wire contract](https://personalclaw.dev/docs/architecture/widgets): An agent-authored is arbitrary HTML with arbitrary scripts. - [Workflows — the Deterministic Orchestration Engine](https://personalclaw.dev/docs/architecture/workflows): A workflow is a declarative graph the engine executes: a spec tree of typed nodes, driven by one conductor per run, with every outcome journaled. ## Security The threat model and an honest account of what PersonalClaw does not protect against. - [Security](https://personalclaw.dev/docs/security): This section is core's own security account of PersonalClaw: a threat model that names the trust boundaries the system is designed around, and a written list of what it does not enforce yet. - [Security Limitations — What We Do Not (Yet) Enforce](https://personalclaw.dev/docs/security/limitations): PersonalClaw's strongest claim is that its controls are enforced at the point of execution, not merely requested in a prompt. - [External Review Scope — Five High-Risk Paths](https://personalclaw.dev/docs/security/review-scope): The threat model claims that PersonalClaw's controls are enforced at chokepoints rather than requested in a prompt, and cites a module for every "enforced" row. - [Scanner Testing — the Published Adversarial Corpus](https://personalclaw.dev/docs/security/scanner-testing): The threat model claims that community content is gated at one chokepoint before it can reach the live skills tree. - [Artifact signing](https://personalclaw.dev/docs/security/signing): How PersonalClaw decides whether an app bundle is from who it says it is, and what that buys. - [PersonalClaw Threat Model](https://personalclaw.dev/docs/security/threat-model): PersonalClaw runs an autonomous agent on the owner's own machine. ## Research The competitive-research corpus PersonalClaw was designed from: 14 topics distilled from 95 sources, published as-written. - [Research](https://personalclaw.dev/docs/research): PersonalClaw was designed from a competitive-research corpus before most of it was built, and this section publishes that corpus rather than summarising it. - [Agent Harness Engineering](https://personalclaw.dev/docs/research/agent-harness-engineering): The harness as the lever over the model: agent loop anatomy, context compaction ladder, tool-output offloading, the ratchet, feedforward/feedback control taxonomy. - [Automation & Triggers](https://personalclaw.dev/docs/research/automation-and-triggers): Always-on background work: scheduler-dispatches-never-executes, the full trigger taxonomy, crash-safe firing, boot sweeps, unattended-vs-interactive policy regimes, pull-over-push. - [Ecosystem & Interop](https://personalclaw.dev/docs/research/ecosystem-and-interop): Distribution and interop: packaging as the product, one canonical source with generated projections, self-describing manifests, two-tool retrieval surfaces, supply-chain trust ladders, protocol adapters… - [Knowledge Pipelines](https://personalclaw.dev/docs/research/knowledge-pipelines): Compile-at-ingest knowledge over query-time RAG: claim schemas with quotes and epistemic stance, deterministic identity and idempotent writes, cost-layered extraction, per-item LLM-call budgets. - [Local Models & Inference](https://personalclaw.dev/docs/research/local-models-and-inference): Model operations as the differentiator: capability flags over failure-time discovery, sidecar process isolation, declarative catalogs, download UX engineering, hardware tiering/quant ladders, backend benchmarking… - [Memory Architectures](https://personalclaw.dev/docs/research/memory-architectures): Typed/tiered memory: injected-memory authority doctrine, relevance-ranks/strength-prunes, extract→decide formation, decay/heat/promotion math, deterministic write-time graphs, graph-walk recall. - [Multi-Agent Orchestration](https://personalclaw.dev/docs/research/multi-agent-orchestration): Coordination: structured state over dialogue, typed handoff schemas, debate as a compilable macro, orthogonal-lens role panels, two-tier model economics, workers-know-their-judge. - [Planning & Task Decomposition](https://personalclaw.dev/docs/research/planning-and-decomposition): The task/workflow/agent taxonomy and 4-question checklist, complexity triage before the planner, tiered template matching, spec fast lanes (never waterfall), graduated evidence-gated autonomy. - [Product Surfaces & UX](https://personalclaw.dev/docs/research/product-surfaces-and-ux): Agent-product UX: generative UI (fault-tolerant streaming spec parsers, registry-constrained rendering, merge-by-name patching), dashboards, decision-ready approval briefs, evidence/proof sections, refresh-on-view. - [Security & Guardrails](https://personalclaw.dev/docs/research/security-and-guardrails): Enforcement over request: chokepoint-gated capabilities, untrusted-content fencing and role-token stripping, capability sets frozen at creation, egress policy tiers, budgets and circuit breakers as security controls. - [Self-Improvement Loops](https://personalclaw.dev/docs/research/self-improvement-loops): Learning flywheels: the ratchet doctrine, traces as the universal substrate, statistical acceptance gates (median-of-N, held-out, monotonic ratchets), propose-don't-write, failure attribution before repair. - [Skills & Prompt Craft](https://personalclaw.dev/docs/research/skills-and-prompt-craft): Skill authoring: SKILL.md anatomy and three-tier progressive disclosure, trigger-shaped descriptions, the invocation-axis taxonomy, a skill-prose failure-mode lint rulebook, token-budget economics. - [Verification & Judging](https://personalclaw.dev/docs/research/verification-and-judging): Judging: self-grading is structurally broken, a loop's floor is its evaluator, act-capable skeptical judges executing ground truth, externalized completion, typed verdict contracts, hidden validation. - [Workflow Engine Design](https://personalclaw.dev/docs/research/workflow-engine-design): Graph/DAG engines: node taxonomies, declarative specs compiled to immutable versions, event-sourced state law, joins/retries/failure envelopes, rewind/fork/replay, mid-flight mutation, the agentic escape hatch. ## Source - [Repository](https://github.com/PersonalClaw/PersonalClaw): the product; docs live in `docs/`. - [Apps](https://github.com/PersonalClaw/PersonalClawApps): first-party app bundles. - [Release provenance](https://personalclaw.dev/release): the exact commits and tags this site was built from.