# 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 and one web dashboard you > own. Local-first and MIT-licensed, with model providers, channels and other vendor > integrations installed as apps. Documentation below describes PersonalClaw v0.3.9 exactly — it is generated from the tagged source, not written separately. PersonalClaw has no analytics, crash reporting or usage telemetry. By default it does ask GitHub whether a newer release exists, when it starts and on an interval after that; the `updates.check_enabled` setting turns that off. This site loads no analytics and makes no third-party requests. [What this release does and does not do](https://personalclaw.dev/compare), each row sourced to the tag. ## 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 is the nginx TLS front that… - [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. - [Keyboard shortcuts](https://personalclaw.dev/docs/guides/keyboard): PersonalClaw's shortcuts, and the rules the approval key follows. - [Your library](https://personalclaw.dev/docs/guides/library): The list holds each thing once, newest activity first: what you pinned at the top, then what you were reading, then today, this week and earlier. - [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: 975 registrations over 790 distinct paths — 968 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… - [PersonalClaw: shared contracts](https://personalclaw.dev/docs/architecture/shared-contracts): This document defines, once, every entity, field, state, event, route and rule that more than one of this release's themes uses, so the theme designs and the tasks filed from them cannot drift apart. - [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. - [Work phases: what an agent is doing, said one way](https://personalclaw.dev/docs/architecture/work-phases): What an agent is doing reaches every surface as one phase of a closed set, which the gateway decides from what it measures and sends as a work_phase frame. - [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.