OpenMuse: a self-hosted personal agent with a browser, terminal and files

What OpenMuse solves, and who it is actually for

Most agent demos stop at a chat box. OpenMuse is built around the claim that an agent needs a computer: a browser it can drive, a terminal it can run commands in, and files it can move around, with the work visible while it happens. The README describes it as a personal-agent application with an agent computer, visible work and rich results, and it ships the server, task worker and browser worker as part of the repository rather than as hosted infrastructure.

The intended audience is narrower than the tagline suggests. The README says the project is alpha and meant for self-hosting and building on, and it points readers to docs/VERIFICATION.md for what is verified. It is not a consumer download. You clone it, install dependencies, supply a CopilotKit Intelligence project key, and run it on your own machine. The reward is that you can inspect and change the source under the MIT license, including the parts that touch your mail and your browser sessions.

The architecture: three processes and a shared data directory

OpenMuse is a pnpm workspace with apps/ and packages/ at the top level. The pieces that matter are the API server, the task worker and the browser worker. The API is a Hono application served through @hono/node-server, and the package.json scripts show it started with tsx watch apps/server/src/index.ts. The task worker runs separately from apps/server/src/worker-entry.ts, and the browser worker runs from apps/worker/src/index.ts.

The separation is not cosmetic. The browser worker has its own dev:browser script, which loads .env and runs apps/worker/src/index.ts, and the README pairs the agent computer with persistent browser profiles and a takeover console.

State lives in a DATA_DIR, which defaults to .openmuse. The .env.example describes an optional separate task worker, with all processes sharing DATA_DIR. The README also mentions SQL leases used to recover interrupted work, so the task system is durable rather than in-memory. Durable plans, progress, input requests, pause, resume, cancel, retry and approvals all live on that Activity surface.

Installing OpenMuse and running the local sample

The README lists three requirements: Node 24 LTS, pnpm 11.19.0, and a CopilotKit Intelligence project key. The packageManager field in package.json pins [email protected], while the engines field asks for node >=22. If you follow the README, use Node 24 LTS.

The quick start clones the repository and installs with a frozen lockfile. The frozen flag matters because this is a workspace with a committed pnpm-lock.yaml:

git clone https://github.com/CopilotKit/OpenMuse.git openmuse
cd openmuse
pnpm install --frozen-lockfile
cp .env.example .env

The next step generates the Intelligence project key. The README uses the copilotkit CLI for both login and project selection:

npx copilotkit@latest login
npx copilotkit@latest project select

After that, set CPK_INTELLIGENCE_API_KEY in .env to the generated server-only project key. The README states that Rich Threads requires this key in every mode, and .env.example says every mode requires a server-only CopilotKit Intelligence project key. Then start the API and, in another terminal, the web client:

pnpm dev

pnpm dev:web

Open localhost:8081. The API health endpoint is at localhost:8787/api/health, which matches PORT=8787 and HOST=127.0.0.1 in .env.example. The default WORKSPACE_MODE=sample and AGENT_BACKEND=sample mean no model, Google account or Docker is needed for this first run.

The README's suggested first task is to send "Complete the permission slip" in Chat, open the task, supply fictional form values, inspect the saved PDF and review the prepared reply. It notes that this writes only to the local mailbox. Two other paths need no model: creating a built-in availability watch under Goals then Track, and using Try example transactions under Menu, Delegate task, Finance to produce a spending tracker. The browser flow is different. It needs the browser worker and a configured model, and the README points to the AI Mock demo setup in docs/DEMO.md for a model-free version. For iOS or Android, the README gives pnpm --dir apps/mobile ios or pnpm --dir apps/mobile android, and notes that Xcode or Android tooling is required.

Where OpenMuse breaks, and when it is the wrong tool

The README is unusually direct about the gaps, and they are the deciding factor. Open-ended reasoning, live Google accounts and CopilotKit Rich Threads all require their own configuration. Graphical desktops and autonomous checkout are listed as future work, which means the agent can drive a browser but you cannot hand it a graphical desktop session.

The connector list is the second boundary. Health, bank and social connectors, device push, voice, generated executable tools, and automatic reservations or payments are all on the roadmap rather than in the alpha. If your use case is paying a bill or booking a table unattended, this is not the tool yet. The Finance surface imports a transaction CSV and produces a spending summary with categories, transactions and a savings-goal action; that is analysis, not payment.

Operationally, the failure modes are configuration-shaped. A missing CPK_INTELLIGENCE_API_KEY blocks Rich Threads in every mode, not just in live mode. Live Google requires WORKSPACE_MODE=live together with AGENT_BACKEND=model, plus OPENMUSE_ACCESS_KEY of at least 24 characters and TOKEN_ENCRYPTION_KEY of 32 random bytes encoded as base64. The OAuth callback is PUBLIC_API_URL plus /api/google/callback, so a wrong PUBLIC_API_URL produces a redirect that Google will reject. There is no tagged release history, so you are tracking main.

The third boundary is the model. General delegated work needs AGENT_BACKEND=model and a provider/model string with the matching key. The .env.example lists OpenAI, Anthropic and Google provider keys, and an optional OPENAI_BASE_URL for an OpenAI-compatible Responses API endpoint. For a gateway model ID such as vendor/model, the comment says to set MODEL=openai/vendor/model. Provider keys stay on the server, which is the right default, but it also means the agent's reach is bounded by whichever provider you wire in.

OpenMuse compared with a plain AG-UI agent endpoint

The most useful alternative is not another personal assistant. It is an agent of your own, and the README's tagline says OpenMuse is compatible with any agent harness.

The difference in approach is what surrounds the agent. OpenMuse's Chat uses CopilotKit headless chat with streamed AG-UI events, and around it sit the persistent browser profiles, durable tasks whose interrupted work SQL leases recover, the PDF pipeline, the Goals and Tracking checks, the Ideas suggestions and the mailbox. So the choice is between letting OpenMuse route conversation through its own model configuration, or keeping your own agent harness and using OpenMuse as the computer and the interface around it.

That framing also explains the tagline about compatibility with any agent harness. If you already have an agent you trust, the interesting part of OpenMuse is the browser worker and the durable task surface, not the routing. If you do not, you are adopting the whole stack, including the CopilotKit Intelligence dependency that the README says is required in every mode.

Licence, maintenance and upgrade cost

OpenMuse is MIT licensed, and package.json carries both the license field and private: true, so it is a private workspace root published under a permissive licence. The repository is not archived, and the last push was on 2026-11-01. There are no tagged releases, so there is no versioned upgrade path to follow.

Upgrade cost is the practical question. The lockfile is committed and the README installs with --frozen-lockfile, which means routine updates are a deliberate pnpm operation rather than an automatic one. The workspace depends on pinned CopilotKit and AG-UI packages, including @copilotkit/runtime 1.70.1 and @ag-ui/client and @ag-ui/core at 0.0.59, plus @tanstack/ai provider packages. Those are the moving parts most likely to force changes when they bump. Because there are no tagged releases, you are tracking main, and the CHANGELOG.md at the repository root is where change history would be recorded.

On licence implications, MIT permits commercial use and modification, and the README explicitly invites cloning the template and customising it. That says nothing about the licences or terms of the model providers, Google APIs or CopilotKit Intelligence, which are separate services with their own terms. If you enable live Google access, the credentials and tokens you store are your responsibility, which is why .env.example asks for a random OPENMUSE_ACCESS_KEY and a base64 TOKEN_ENCRYPTION_KEY.

Editorial conclusion

OpenMuse suits engineers who want to read and change the source of a personal agent and who are willing to run a server, a task worker and a browser worker themselves. It is the wrong choice if you want a finished product, since the README labels it alpha and lists graphical desktops, autonomous checkout, health/bank/social connectors, device push and voice as future work. Before adopting it, verify that the CopilotKit Intelligence project key path works for you, that Node 24 LTS and pnpm 11.19.0 are available, and that you can supply the Google OAuth credentials if you need live Gmail or Calendar rather than the local sample mailbox.

Frequently asked questions

Official sources

1. CopilotKit/openmuse on GitHub
2. Issues
3. License: MIT
4. README