OpenMuse

Personal agent with a browser, files, goals and a live Google workspace.

Overview

OpenMuse is a personal-agent application from the CopilotKit team: a chat surface over an agent that has its own files, durable task plans, goals and tracking watches, PDF handling and a Google workspace. It is built with CopilotKit React Native and AG-UI, and the same codebase ships as an iOS and Android app.

Upstream publishes no container image. Its only deployable artifact is a Render blueprint (render.yaml) that builds three services from source and runs them as a live workspace driven by a real model. This template follows that blueprint: it builds its own image from a pinned commit (see ./Dockerfile), and ships the same WORKSPACE_MODE=live, AGENT_BACKEND=model, MODEL=openai/gpt-5 configuration. Inside the image, nginx serves the Expo web bundle and proxies /api to the Node API on loopback, because a template gets one routed port while upstream's API answers / with JSON and expects its UI to be a separate static site.

The browser worker is included, the way upstream's own blueprint splits it: upstream's apps/worker (a Playwright Chromium service) is a second image, so it is built by the companion openmuse-browser template and run here as the browser service, which the API reaches over the network. It gives the agent page reads, screenshots and Take control. The two services share a WORKER_TOKEN minted at deploy, so there is nothing to configure.

One part of upstream is still not here:

• The Linux computer. Its Terminal and Files run shell commands inside a container the API repeatedly docker execs into, which needs a Docker engine the compute machine does not provide. COMPUTER_ENABLED is fixed to false.

What you get by hosting it

• The web app and the API behind one HTTPS URL.
• A live workspace: the agent runs against a real model, and Gmail and Calendar connect through Google OAuth.
• A browser the agent drives: page reads, screenshots and Take control, served by the browser service that ships with this template.
• A persistent volume at /data, holding the PGlite database, imported and filled PDFs, the session signing key and the token-encryption key, so a restart keeps your work.
• The task worker running in-process: tracking watches re-check pages on their own schedule and SQL leases recover tasks interrupted mid-run, which is why the service is always-on.

What you need before deploying

• A workspace access key of your choosing, at least 24 characters. OpenMuse's own sign-in screen asks for it; it is the app's only password.
• A CopilotKit Intelligence project key. Run npx copilotkit@latest login and then npx copilotkit@latest project select. The server refuses to start without it, before it binds a port, so this is not optional configuration.
• An OpenAI API key, for the default MODEL=openai/gpt-5. To use a different provider, set MODEL to an anthropic/* or google/* id and supply that provider's key instead.
• For Gmail and Calendar: a Google OAuth client. Its redirect URI is this service's URL plus /api/google/callback, which you only know after the first deploy.

Configuration

Set by the template, not by you: HOST=127.0.0.1 and the API's port 8787 (the API binds loopback and nginx is the public face), WORKSPACE_MODE=live, AGENT_BACKEND=model, MODEL=openai/gpt-5, DATA_DIR=/data/openmuse, TASK_WORKER_ENABLED=true, COMPUTER_ENABLED=false, and PUBLIC_API_URL and ALLOWED_ORIGINS resolved to the service's own HTTPS URL, which is what signed document links and the Google OAuth redirect are built from.

The service is always-on. Tracking watches and interrupted-task recovery run from inside the process on a schedule, and no inbound request would wake a stopped machine for them.

After deploy

1. Open the service URL. OpenMuse's sign-in screen asks for the workspace access key; enter OPENMUSE_ACCESS_KEY.
2. The workspace opens. Chat talks to the agent through your CopilotKit Intelligence project and the model you configured.
3. In Goals, create a goal or a tracking watch; it is stored on the volume and survives a restart.
4. For Gmail and Calendar, add a Google OAuth client whose redirect URI is https://<your-service-url>/api/google/callback, set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, then connect from Apps.

Links

• Architectures: linux/amd64 only. Nothing in the build is architecture-specific, but the arm64 leg has not been run; see the architectures table in the registry README.
• Upstream: https://github.com/CopilotKit/OpenMuse, built from commit 9ec439fbaa878197d9d44c2aa982cca55676dd68.
• Image: ghcr.io/insforge/insta-oss/templates/openmuse, built from ./Dockerfile in this directory.
• License: MIT (upstream CopilotKit/OpenMuse).