Build from source

You don't need to build Murage to use it: the download page has signed installers for Mac and Windows and packages for Ubuntu. Build from source when you want to change Murage or check exactly what you're running.

Requirements#

• Node 24 or newer.
• pnpm. The project declares pnpm 10.33.0; Corepack can install it (corepack enable).
• At least one agent CLI installed and signed in, if you want to actually chat with a bot: for example Claude Code (claude) or Codex (codex).
• For Mac packages: Swift and Xcode tools.

macOS is the primary release platform, and Ubuntu 24.04 x64 is the Linux desktop beta. The server is portable Node, and the test suite runs on macOS, Linux and Windows.

Get the code#

git clone https://github.com/FerroxLabs/murage
cd murage
pnpm install

Run it in development#

Run these in separate terminals:

pnpm dev:server    # harness server on 127.0.0.1:8799
pnpm dev           # the app on http://127.0.0.1:5199
pnpm dev:desktop   # Electron shell (macOS and Ubuntu); keep the server and Vite running

pnpm dev:desktop downloads and verifies the pinned Cloudflare Tunnel connector for your platform before Electron starts, and reuses it on later launches.

Development data lives in ~/.murage/ like a normal install. To keep a test setup away from your real bots, the server honors MURAGE_DATA_DIR, which points it at a different data folder.

Check your work#

pnpm typecheck       # app and server
pnpm test            # the full suite
pnpm test:watch      # vitest in watch mode
pnpm check:electron  # syntax-check the plain JS Electron entry points
pnpm lint            # oxlint

pnpm typecheck and pnpm test must pass before a pull request is merged.

The test layers#

Tests sit next to the code (server/**/*.test.ts). There are four layers:

• Unit: registry, bus and store, in process, using the fake driver in server/testing/fake-driver.ts.
• Driver contract: tests that spawn scripted fake claude and codex CLIs from server/testing/ and assert the canonical event stream, argument and environment hygiene, interrupts and the permission broker. Failure modes are switched with environment variables such as FAKE_CLAUDE_MODE=exit-early. Extend the fakes rather than mocking child_process.
• API smoke: server/index.test.ts boots the real server against a throwaway home folder and exercises the HTTP API.
• Human specs: pnpm test:human runs Playwright specs in src/e2e/ against a scratch harness on its own ports. It refuses to run without MURAGE_E2E_DATA_DIR, which must point outside the repository, for example MURAGE_E2E_DATA_DIR=/tmp/murage-e2e pnpm test:human.

House rules for tests:

• No sleeps. Wait on the event that proves the behavior, using recordEvents(...).until(...) from server/testing/events.ts.
• Never touch the real ~/.murage. The test setup points HOME at a temporary folder.
• Launch fake CLI scripts through spawnCli or execCli, which handle Windows.

Package a desktop build

pnpm package:mac     # DMG and ZIP; needs Swift and Xcode tools
pnpm package:linux   # Ubuntu x64 .deb and AppImage; no Swift needed

There's also pnpm package:win for Windows. Packaging stages the pinned native pieces each platform needs (such as the backup tools, the Cua Driver and the Fuigo engine) before running electron-builder.

On Ubuntu, packages must be built on Ubuntu 24.04 x86_64. The build writes release/Murage-<version>-amd64.deb and release/Murage-<version>-x86_64.AppImage. Check a Linux package with:

node scripts/verify-linux-package.mjs

Official releases aren't built on developer machines. See Release process.

Other useful commands

• pnpm build: typecheck and build the app and server.
• pnpm build:server: build the server bundle into dist-server/. That folder is build output: never edit it by hand or include it in a pull request.
• pnpm mcp: run Murage's MCP server from source, for another MCP client.
• pnpm i18n:check: check translation files.
• pnpm catalog:check and pnpm catalog:build: check or rebuild the team library catalog.

Repo map

• server/contracts.ts: the driver interface and runtime event types. Read it first.
• server/drivers/: one file per engine; register new ones in builtIn.ts.
• server/harness/: the registry and the event bus.
• server/index.ts: the HTTP and SSE API.
• server/testing/: fakes and scripted fake CLIs.
• src/: the React app.
• electron/: the desktop shell.
• shared/: types used by both app and server.
• library/: team packages and the catalog.
• skills-library/: the shipped skill library.
• apps/docs/: the in-repo documentation site.

See Architecture overview for how they fit together.