Clawdi

The best home for all your AI agents — Projects, sessions, memory, skills, vault, model providers, and app connections.

Website · GitHub · Docs · npm · Architecture · AI Providers · Quickstart · CLI Reference · Troubleshooting

Think of Clawdi as iCloud for AI agents — install once on any device, and your Claude Code, Codex, Hermes, and OpenClaw agents share memory, secrets, Skill inventory, sessions, and app connections. Agent Skill files remain authoritative on their own filesystems.

The fastest way to try it is hosted Clawdi Cloud. The whole stack is also here: MIT-licensed CLI, FastAPI backend, TanStack Start dashboard, database schema, migrations, and docs. Use the hosted service, self-host it, fork it, or build your own agent sync layer from the pieces.

Quickstart

Recommended on macOS and Linux (no Node.js required):

curl -fsSL https://clawdi.ai/install.sh | sh

clawdi auth login
clawdi setup
clawdi doctor

On Windows, or when you prefer a package-manager-owned installation, use npm with Node.js ≥ 22.5:

npm i -g clawdi

That gets you:

• Browser-based login to Clawdi Cloud
• Agent auto-detection for Claude Code, Codex, Hermes, and OpenClaw
• MCP registration so your agent can call Clawdi tools
• The bundled clawdi skill installed into each detected agent
• Background sync daemons installed and started for every registered agent
• A health check that verifies auth, agent paths, vault access, and MCP config

By default the CLI talks to hosted Clawdi Cloud. Want to run your own backend? See Own the Stack.

Native installations update from checksum-verified exact GitHub Release assets. npm/Bun installations update through their current package manager. Hosted CLI transactions remain separate and select an exact npm version.

With Node.js ≥ 22.5, you can also try without installing:

npx clawdi --help

SSH or headless environment? Keep the same Clerk login and print the PKCE URL:

clawdi auth login --no-open

Open the URL on your local computer. If the browser cannot reach the registered loopback callback on the remote machine, copy the complete failed callback URL from the browser address bar and paste it into the CLI's masked prompt. For a non-interactive first step, finish later with clawdi auth complete and provide that URL on stdin; never put the authorization code in a command-line flag. --manual is retained only for legacy Cloud API keys and cannot deploy Hosted agents.

Why Clawdi

AI agents are still treated like isolated apps. Claude Code has one set of sessions and instructions. Codex has another. Secrets sit in shell profiles and .env files. Useful memories get trapped in whichever agent happened to learn them. App integrations get rebuilt from scratch every time you switch tools.

Clawdi is the shared layer underneath:

• Cross-agent memory — Store durable preferences, decisions, facts, and project context once. Search them from any connected agent.
• Portable skills — Author instructions in each Agent's guarded filesystem and project a read-only Cloud inventory; explicitly import Cloud-owned Project Skills when needed.
• Project sharing — Share read-only Project access from the dashboard or CLI, accept it from a share page or CLI inbox, and explicitly attach accepted Projects to Agents when they should be used at runtime.
• Session sync — Push local session history to the dashboard for review and recall.
• Vault secrets — Store secrets server-side, commit only clawdi:// references, and resolve them at runtime.
• AI Providers — Keep a multi-record provider catalog and auth references while Core Hosted manifests bind at most one provider to Hermes or OpenClaw, without proxying BYOK model traffic.
• App connections — Hook agents into Notion, Gmail, Drive, Calendar, Linear, GitHub, and more from the dashboard. Tools show up inside every connected agent automatically over MCP.
• MCP tools — Memory, vault, and connector tools served through the Model Context Protocol so any MCP-aware agent can use them.

In practice — teach one agent something:

remember that this repo uses Bun for TypeScript, uv for Python dependencies, and PDM for backend scripts

Later, in a different agent or a fresh session, ask "what package manager should I use here?" — it can call Clawdi memory search and answer from your actual context instead of guessing.

Run a fullstack dev command with vault references without putting plaintext secrets on disk:

printf '%s\n' "$OPENAI_API_KEY" | clawdi vault set OPENAI_API_KEY --stdin
clawdi vault import --vault prod --section stripe --project personal --yes .env.stripe
echo "OPENAI_API_KEY=clawdi://project/<project-id>/vault/default/field/OPENAI_API_KEY" > .env.clawdi
clawdi run --dry-run --env-file .env.clawdi -- npm run dev
clawdi run --env-file .env.clawdi -- npm run dev
clawdi read clawdi://project/<project-id>/vault/default/field/OPENAI_API_KEY
clawdi inject --dry-run --in .env.clawdi --out .env.local
clawdi inject --force --in .env.clawdi --out .env.local

Vaults are account-level key bundles. Projects attach to a Vault to use the same shared key set. clawdi vault set, clawdi vault import, clawdi vault rm, and clawdi vault list print the concrete Project target or exact references that include the Project ID. vault set supports --value and --stdin for scripts; vault import supports --vault, --section, --project, and warns about skipped invalid dotenv identifiers. Use clawdi vault attach <vault> --project <project> to make an existing Vault available in another Project, and clawdi vault detach <vault> --project <project> to remove one Project's access without deleting keys. vault rm deletes a key from the shared Vault; when a Vault is attached to multiple Projects, it requires --global. Project-relative references such as clawdi://default/OPENAI_API_KEY still work for portable templates, but exact references are the default copy/read UX.

Agents should prefer clawdi run --env-file .env.clawdi -- <command> when they can launch the tool themselves. Use clawdi inject only for tools that must read a physical .env.local; generated files are written owner-only and should stay gitignored.

Use --dry-run on clawdi read, clawdi inject, clawdi run, and clawdi vault resolve to verify provenance without requesting plaintext values. clawdi doctor checks vault metadata only; it does not resolve stored secrets.

Sync a local CLI credential profile to another machine. For Codex model-provider auth, prefer the AI Provider commands in the next section; the lower-level agent credentials commands remain available for compatibility and for non-provider CLI credentials such as Claude Code and GitHub CLI.

clawdi agent credentials import claude-code
clawdi agent credentials import gh
clawdi agent credentials materialize claude-code
clawdi agent credentials materialize gh

Credential profile sync is separate from clawdi run: it stores and restores a supported tool's local auth file, while run injects explicit clawdi:// references into one child process. Profiles default to your stable Personal Project so import on one machine and materialize on another resolve the same namespace. They are personal backup/restore artifacts: shared Project viewers and env-bound Agent keys cannot materialize them. macOS Keychain imports are guarded behind --source keychain and require explicit --keychain-service plus --keychain-account; Clawdi does not guess or silently scrape credential-store items, and Keychain reads cannot use --yes.

Manage model providers without turning Clawdi into a model proxy:

clawdi ai-provider add openai-main \
  --type openai \
  --default-model gpt-5.2 \
  --auth env:OPENAI_API_KEY \
  --capability chat \
  --capability responses \
  --capability tools

clawdi ai-provider validate openai-main
clawdi ai-provider test openai-main        # config + auth availability
clawdi ai-provider test openai-main --live # optional direct provider probe

AI Provider metadata lives in ~/.clawdi/ai-providers/catalog.json; API keys do not. Use env:... refs, clawdi://... Vault refs, none for local unauthenticated endpoints, or a verified auth profile such as agent:codex/default. BYOK model requests still go directly from the agent runtime to OpenAI, Anthropic, OpenRouter, Gemini, Mistral, or your compatible endpoint.

Codex OAuth is connected through the AI Provider surface:

clawdi ai-provider add openai-codex \
  --type openai \
  --default-model gpt-5-codex \
  --auth agent:codex/default
clawdi ai-provider connect openai-codex --tool codex

Local Provider Catalogs may contain many records. Core Hosted activation comes from the stable runtime manifest/controller path: configured Hermes or OpenClaw binds exactly one provider_ids entry, while unmanaged mode binds none. Selection is replacement-only, with no fallback or secondary pool.

Each Codex OAuth credential family still has one Hosted runtime owner. Hermes uses its native auth store and OpenClaw uses its database-first openclaw-agent.sqlite store through the public provider-auth SDK. Clawdi seeds a missing owned entry but preserves target-native token refresh and durable revoke state.

Use clawdi ai-provider connect ... --callback manual in headless environments. Export/import is metadata-only by default; --include-secrets requires passphrase-encrypted secret export.

Current vault storage is server-managed encryption. Clawdi avoids plaintext secrets in repo files and local templates, but the backend can decrypt stored vault values and credential profiles today. Do not treat this release as zero-knowledge.

Install a public Skill into one Agent's authoritative local root:

clawdi skill install anthropics/skills/artifacts-builder --agent claude_code

Roadmap

Today Clawdi gives individuals and read-only Project collaborators a shared layer across their agents. Two bigger bets come next.

The first is autonomy. Agents should work without you at the keyboard.

• Cron jobs for recurring agent runs.
• Remote control for agents on any of your machines.
• Automatic memory built from session history.

The second is deepening multi-player workflows beyond read-only Project sharing.

• Richer team roles and broader access controls.
• Shared memory, skills, and connections.
• An agent-to-agent channel for handoff and ask-for-help.
• Task tracking that every connected agent can use.

We'll also keep adding adapters. Cursor, OpenCode, Amp, Pi, and others. The same memory, skills, and connections follow you everywhere.

Want any of this sooner? Open an issue. What's loud is what we build first.

Hosted or Self-Hosted

Clawdi has two intended paths.

Use Clawdi Cloud

Best for trying it in minutes.

curl -fsSL https://clawdi.ai/install.sh | sh
clawdi auth login
clawdi setup

The published CLI defaults to the hosted API. You get the least setup friction and can focus on wiring agents, memories, skills, and vault secrets.

Own the Stack

Best when you want to inspect, modify, self-host, or build on Clawdi.

git clone https://github.com/Clawdi-AI/clawdi.git
cd clawdi

For the canonical backend + dashboard + CLI local runbook, see AGENTS.md#local-end-to-end. It covers dependency install, local env keys, VITE_CLAWDI_API_URL, dev auth bypass, local API key minting, health checks, clawdi doctor, and cleanup.

Local self-hosting currently expects:

• Node.js 22.5+ and Bun 1.3+
• Python 3.12, uv for dependency sync, and PDM for backend scripts
• PostgreSQL 16 with pg_trgm and pgvector
• Clerk keys for dashboard auth
• Two generated encryption keys for vault data and backend security material
• One backend process until v1.5. The clawdi daemon realtime SSE fan-out lives in process memory (backend/app/services/sync_events.py), so a broadcast on worker A doesn't reach a daemon attached to worker B. Run a single uvicorn worker (or one gunicorn worker with --workers 1) behind your reverse proxy. Multi-process fan-out via Postgres LISTEN/NOTIFY ships in v1.5.

See backend/.env.example and apps/web/.env.example for the exact environment variables.

What Is In This Repo

apps/web/          TanStack Start dashboard with Clerk auth, shadcn/ui, Tailwind v4
packages/cli/      Published `clawdi` CLI, agent adapters, and MCP server
packages/shared/   Shared API types, schemas, and constants
backend/           FastAPI backend, SQLAlchemy models, Alembic migrations
docs/              Architecture notes, scenarios, and development guides

The system is deliberately boring where it should be:

• FastAPI API server
• PostgreSQL for structured data and memory search
• File storage for session and skill bodies
• Local CLI state under ~/.clawdi
• MCP stdio server spawned by each agent
• No Redis, Celery, or hidden worker fleet required for the core local stack

For the deeper map, read docs/architecture.md.

Supported Agents

Agent	Sessions	Skills	MCP setup
Claude Code	Yes	Yes	Automatic
Codex	Yes	Yes	Automatic
Hermes	Yes	Yes	Automatic
OpenClaw	Yes	Yes	Manual MCP hint where required

Each agent has a dedicated adapter in packages/cli/src/adapters. Adding another agent means implementing the same adapter shape: detect it, read sessions, read/write skills, and define how commands run with injected env.

CLI Reference

Command	What it does
clawdi auth login / logout	Authenticate this machine
clawdi auth status [--json]	Show credential source without printing secrets
clawdi deploy [--json]	Create a Hosted agent with interactive or automation-safe payment handling; every non-interactive deploy requires a caller-supplied --request-id <uuid> before create or checkout mutation
clawdi status [--json]	Show auth and sync state
clawdi config list/get/set/unset/paths	Read/write CLI configuration and inspect local/runtime paths
clawdi setup [--agent <type>] [--no-daemon]	Register local agents, install MCP, install the bundled skill, and install/start the singleton daemon by default
clawdi teardown [--agent <type>]	Remove Clawdi's local agent wiring
clawdi daemon run/install/status/logs/doctor/restart/uninstall/ping/rotate-token	Run, inspect, and control the singleton background sync daemon (serve remains a legacy alias)
clawdi push	Upload sessions and skills
clawdi pull	Mirror cloud sessions, or explicitly import Skills from a workspace/personal Project with --project
clawdi session list/extract	Inspect local agent sessions
clawdi memory list/search/add/rm	Manage cross-agent long-term memory
clawdi skill list/add/install/rm/init	Manage portable skills
clawdi project create/list/show/share/share-links/invite/invites/members/leave/unshare	Manage Projects and read-only sharing
clawdi inbox [accept/decline/forget]	Accept invitations and share links
clawdi agent projects list/attach/detach/move	View the fixed Agent Project and manage attached Projects
clawdi agent credentials import/materialize	Compatibility backup/restore for local CLI credential profiles; use ai-provider import-auth/connect for Codex provider auth
clawdi ai-provider list/add/edit/remove/validate/test/connect/complete-oauth/import-auth/export/import	Manage local provider catalog records, auth refs, Codex OAuth/profile auth, direct tests, and provider-only export/import; Core Hosted activation comes from the runtime manifest/controller
clawdi channel list/available/get/create/links/link/rotate-token/pair-code/send/bindings/sync-commands/delete	Manage channel bots, bot-agent links, chat pairing, outbound messages, and provider slash-command sync
clawdi project folder link/status/unlink	Link a local folder to a Project for vault reference selection
clawdi vault set/list/import/attach/detach/rm/resolve	Manage encrypted secrets, Project access, exact references, and dry-run/explicit secret resolution
clawdi read <clawdi://...>	Explicitly print one vault reference value
clawdi inject --in <file> --out <file>	Render clawdi:// references into templates
clawdi run --env-file <file> -- <cmd>	Run a command with explicit vault references resolved
clawdi doctor	Diagnose auth, agent paths, vault, and MCP config
clawdi update	Install the latest CLI version (--check only reports)
clawdi mcp	Start the MCP stdio server used by agents

Auto-update is enabled by default for all newer releases, including majors. Human CLI invocations update the global CLI in the background; installed daemons check on their own cadence, install silently, then let launchd/systemd restart them onto the new code. Disable both with CLAWDI_NO_AUTO_UPDATE=1 or clawdi config set autoUpdate false.

Every command supports --help.

Advanced Runtime Operators

These commands are for controlled managed runtime environments. They are not part of normal laptop onboarding.

Command	What it does
clawdi capabilities [--json]	Show CLI feature surface, runtime mode, and policy restrictions
clawdi runtime init/watch/status/doctor	Converge, watch, inspect, and diagnose runtime state
clawdi runtime plan/apply/status --file <manifest>	Preview, apply, and inspect channel runtime manifest projections

Runtime mode is detected from policy or runtime credentials. In managed mode, policy can deny local-user setup and mutation commands while keeping agent-facing commands such as mcp, daemon run, read, inject, and run available. Local self-update can be skipped when updates are managed by the runtime environment.

For the public managed runtime CLI contract, see docs/managed-runtime.md.

App connections are configured in the Clawdi Cloud dashboard and surface inside agents automatically over MCP — there is no CLI command to manage them.

Development

The clean default verification path runs inside Docker and keeps the host repo read-only during test execution:

scripts/test.sh          # JS typecheck/tests, then backend pytest
bun run test             # same clean Docker runner
scripts/test.sh ci       # focused CI harness profile; not a product test replacement
scripts/test.sh js       # JS typecheck + web/shared/sidecar/CLI tests
scripts/test.sh cli      # CLI typecheck + full CLI tests
scripts/test.sh shared   # shared package typecheck + tests
scripts/test.sh sidecar  # WhatsApp sidecar typecheck + tests
scripts/test.sh web      # web typecheck + tests + OSS build only
scripts/test.sh backend  # Alembic + backend pytest against throwaway Postgres

The runner copies the read-only checkout into an isolated non-root container workspace, uses a fake HOME, disables CLI update checks, and keeps Bun/uv caches in container tmpfs paths. /tmp is an executable tmpfs so tests can run their own temporary stub binaries without touching the host. Dependency caches are intentionally per-run inside the container; only Docker image layers and build cache are reused by the Docker daemon. It does not force CLAWDI_HOME, so tests can still isolate Clawdi state through the same home/config paths as the product. Backend tests use a temporary pgvector/pgvector:0.8.1-pg16 Postgres service and do not reuse the dev database.

Clean Test Runner CI uses the first-class ci profile to exercise the runner contract in one container without repeating the full web and CLI product suites. The normal all, js, web, cli, shared, sidecar, and backend entrypoints retain their comprehensive behavior. Core runner changes can use the workflow's manual suite=all dispatch gate without adding full-suite duplication to routine pull requests. See docs/clean-test-runner.md for the exact focused suite, measured resource envelope, and override variables.

For a focused CLI pytest-style argument pass-through, append paths after the suite name, for example scripts/test.sh cli tests/api-client.test.ts. The public package-level test scripts also route through this Docker runner. Explicit host-local development loops remain available from the workspace root through bun run test:local; test:internal is reserved for the runner and CI.

Install workspace dependencies from the repo root:

bun install

Install backend dependencies:

cd backend
uv sync

Run the web app and workspace dev tasks from the repo root:

bun run dev

Run the backend:

cd backend
pdm dev

Run workspace checks from the repo root:

bun run check
bun run typecheck

Host-local commands are still useful for fast opt-in development loops after you have installed dependencies locally. Run backend checks with the Ruff, compile, and throwaway-Postgres pytest flow in docs/backend-development.md#verification.

Run the CLI from source:

bun run packages/cli/src/index.ts --help

Build and link the CLI locally:

cd packages/cli
bun run build
bun link
clawdi --version

Troubleshooting

Run the diagnostic first:

clawdi doctor

Common issues:

• clawdi auth login fails - Re-run login; over SSH use clawdi auth login --no-open and paste the complete failed loopback callback URL. --manual is legacy API-key compatibility and does not authorize Hosted deploys.
• No supported agent detected - Install a supported agent or pass --agent claude_code, --agent codex, --agent hermes, or --agent openclaw.
• Memory search is empty - Add a memory first with clawdi memory add "...", then verify with clawdi memory search "...".
• Local backend cannot start because vector is missing - Install pgvector for your PostgreSQL 16 instance, or use the included Docker Compose database.
• Agent MCP tools look stale - Run clawdi setup --agent <type> again, then clawdi daemon restart.

License

MIT. See LICENSE.

Star Trends