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 keeps persistent Chromium profiles under WORKER_DATA_DIR, which defaults to .openmuse/browser-profiles, and it listens on its own host and port. The .env.example shows BROWSER_WORKER_URL defaulting to http://127.0.0.1:8790 and a WORKER_TOKEN that must be the same random 32+ character secret in both the API and the browser worker. The API and the browser worker authenticate to each other with that token, so a mismatched value breaks the browser surface.

State lives in a DATA_DIR, which defaults to .openmuse. The comment in .env.example notes that all processes share DATA_DIR for PDF files, which is why an optional external Postgres via DATABASE_URL is described as an optional separate task worker rather than a replacement. 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, and the .env.example repeats the same commands in its comments:

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 the PDF reader needs an Expo development build.

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 or mismatched WORKER_TOKEN between the API and the browser worker disconnects the browser surface. 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. The README does not document a rollback path for a failed live-mode migration, and 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 the thing OpenMuse already supports as a mode: AGENT_BACKEND=agui with AGENT_URL pointing at your own raw AG-UI agent endpoint and AGENT_TOKEN for authentication. The .env.example is careful here, noting that an external raw AG-UI agent replaces conversational routing only, and that OpenBot's Intelligence runtime is not this raw AG-UI URL.

The difference in approach is where the state lives. A raw AG-UI endpoint owns its own conversation and tool loop, and OpenMuse hands it the chat. Everything else in the application, the persistent browser profiles, the task worker with its SQL leases, the PDF pipeline, the Goals and Tracking checks, the Ideas suggestions, the mailbox, stays on OpenMuse's side and keeps running. 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-09-26. That is the only maintenance signal available; 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. This is a description of what the files say, not legal advice.

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