A local-first runner for AI coding agents across your machines.
Domovoi puts a daemon beside the code and renders its sessions in desktop and browser clients. Repository state, credentials, terminals, worktrees, and tool execution stay on the execution machine. Clients receive typed state, diffs, terminal streams, approval requests, and sandboxed preview documents.
This repository is early. The current vertical slice includes:
- strict TypeScript and pnpm workspaces;
- a versioned Zod protocol with permission, runtime, machine, session, approval, thread, and artifact schemas;
- an authenticated Node daemon with health and WebSocket JSON-RPC endpoints;
- a shared React workspace rendered by Vite and Electron;
- custom Electron window decoration with a sandboxed, context-isolated renderer;
- daemon-backed approval and runtime state changes;
- Claude Design's signed desktop layout and Domovoi spirit mark implemented with Tailwind v4, shadcn/ui, and Radix.
apps/
cli/ domovoi terminal client: pair, status, doctor, logs, skill install
daemon/ domovoid execution service and JSON-RPC endpoint
desktop/ Electron client
mobile/ Expo phone and tablet app, see apps/mobile/README.md
web/ browser client and installable PWA
packages/
credential-store/ publishable keychain or private-file custody for client credentials
protocol/ publishable wire schemas and shared types
ui/ shared product UI and brand assets
design/
design_handoff_domovoi/ signed v1 product-design source
design_handoff_domovoi_brand/ signed brand source
design_handoff_domovoi_v2/ v2 handoff the current clients are built from, see DESIGN.md
design_system_domovoi/ signed design system: tokens, specimens, and the
adherence manifest scripts/design-rule.mjs reads
To take a machine that has nothing installed through a daemon runtime, first start, TLS, supervision, fleet pairing, and Windows to WSL access, follow clean-machine setup. It is written for the operator of that machine and names what is still unproven per platform. The rest of this page is repository development.
Requirements: Node.js 22.13.0 or newer and pnpm 11.
pnpm install
pnpm build
pnpm devpnpm dev starts domovoid on 127.0.0.1:47831 and the browser client on
127.0.0.1:5178. Run the Electron shell separately:
pnpm dev:desktopTo work on the interface itself, run the desktop shell against a fixture daemon instead of a real one:
pnpm dev:desktop:fixtureThis opens the real Electron window against apps/desktop/scripts/dev-fixture-daemon.mjs, a
separate process that speaks the protocol. It looks each request's method up in the protocol's
rpcMethods and validates that method's params, and its own answer, against the schemas in
packages/protocol. It never touches ~/.domovoi, and it refuses any method it has no handler
for, naming the method and the file to add it in, rather than answering with something plausible.
Because it is its own process, its state survives a window relaunch.
For hot-reloading UI against the real local daemon and its real sessions, gates, worktrees and provider credentials, start that daemon in one terminal:
pnpm --filter @getdomovoi/daemon startThen, from the repository root, run:
pnpm dev:desktop:realFrom apps/desktop, pnpm dev:real and pnpm dev:desktop:real are equivalent.
This reads the endpoint and credential from the profile selected by DOMOVOI_PROFILE_DIR, or
~/.domovoi/endpoint.json and ~/.domovoi/daemon.token by default, then attaches without
acquiring the profile or stopping the daemon.
Only unpackaged loopback WebSocket endpoints are accepted. Set DOMOVOI_DEV_DAEMON_URL to an
explicit loopback URL when the development daemon uses another port. Quit the installed Domovoi
app first if it owns the default profile, or run the development daemon with a separate profile
and port. The credential is passed only to the development Electron process and is never printed.
Use pnpm dev:desktop:fixture for states that are hard to produce safely on demand, including
policy refusals, unreachable machines, partial transfers and mid-turn disconnects. Both commands
use the same watched Electron window: renderer edits apply in place, while main and preload edits
relaunch onto the same selected daemon.
Every watched save prints a line naming the file and what should happen next. An edit under
packages/ui/src, apps/desktop/src/renderer or apps/desktop/src/dev prints a renderer-update
line and applies in place, keeping the window state; if
Fast Refresh cannot apply it, a second line says the renderer reloaded and the window state is
gone. An edit under apps/desktop/src/main or apps/desktop/src/preload relaunches the window on
the same selected daemon, and the relaunched window prints a boot line. Saves elsewhere, and saves
to test files, print nothing. An unchanged window after a watched save therefore always has a line
beside it saying what was supposed to happen.
Every daemon requires authentication. Standalone domovoid creates a user-private credential at
~/.domovoi/daemon.token when DOMOVOI_AUTH_TOKEN is unset. Remote listeners additionally require
DOMOVOI_ALLOW_REMOTE_TRANSPORT=1 plus DOMOVOI_TLS_CERT_PATH and DOMOVOI_TLS_KEY_PATH; the
daemon terminates TLS itself and refuses a plaintext non-loopback listener. Set
DOMOVOI_ALLOWED_ORIGINS to a comma-separated list of trusted browser origins. The browser client
dials ws://127.0.0.1:47831/rpc by default; set the build-time Vite variable
VITE_DOMOVOI_RPC_URL, read by apps/web/src/main.tsx, to point it at another daemon WebSocket
URL. Preview documents
on every listener, loopback included, require short-lived signed capabilities scoped to one
artifact revision, purpose, annotation bridge channel, and parent origin.
File-backed credentials are written, synced and closed in private staging before a no-replace
hard link publishes the final name. An interrupted first write therefore does not publish an
empty daemon.token or local-owner.key. Existing malformed files are preserved and startup
names their path; see credential initialization and offline recovery
before quarantining one. Initialization requires a filesystem with hard-link support.
For supervised operation, domovoid service install saves validated non-secret daemon settings and
uses them on every service start. Environment-only bearer tokens are not copied into service files.
See daemon service configuration for credential setup and lifecycle limits.
For a stranded legacy or custom-supervised profile, domovoid profile recover --confirm-no-supervisor
records an explicit assertion that no supervisor will restart it. Stop those supervisors first.
The command requires a free profile lease; deleting service.json is not proof of shutdown.
See local owner recovery before using it.
pnpm typecheck
pnpm test
pnpm buildAlpha performance limits and the local/CI budget command are documented in
docs/performance-budgets.md.
- Daemon owns canonical session state.
- Code and secrets stay on the execution machine.
- Ask, Plan, and Build are permission modes. Auto is a separate control.
- Hard gates require explicit approval.
- Cross-provider handoffs carry documented Domovoi state, not hidden provider reasoning or caches.
- Clients collapse information for smaller screens; they do not omit approval facts.
- Preview documents execute only inside sandboxed artifact containers.
Open product decisions are tracked in
design/design_handoff_domovoi/OPEN-QUESTIONS.md.
The one delivery plan is SHIP-PLAN.md; the working rules the agents hold each
other to are in docs/working-rules.md. Agent-facing conventions and
the verified command set are summarized in AGENTS.md.
Domovoi is open-core. This repository contains the Apache-2.0-licensed daemon, protocol, clients,
and local transports. The daemon's Claude Code session adapter depends at runtime on the
proprietary @anthropic-ai/claude-agent-sdk. npm installs it under Anthropic's terms; the desktop
app bundles its JavaScript library but not its agent binary. The daemon runs the person's own
installed claude. That exception is recorded in docs/licensing.md.
Future hosted account, billing, relay, encrypted vault, and team-policy services may live outside
this repository.