leapmux/leapmux
leapmux/leapmux has 120 GitHub stars and 10 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:48 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
AI Coding Agent Multiplexer
AIREADME.md
OriginalLeapMux
Shell tabs work well for one or two coding agents. With three or four agents, you can lose track of which agent owns each branch. Agents can overwrite each other's work in a shared working tree. A tmux crash or machine restart requires you to resume each agent and restore the layout manually.
LeapMux runs several coding agents and shell terminals in one workspace. Choose each agent's git worktree and branch. Arrange the views in tiles or floating windows on a local or remote machine. Sessions stay attached across restarts. LeapMux encrypts Frontend↔Worker traffic from end to end. Use LeapMux in a browser or as a native desktop app.
Supported Agents
📖 Want to use LeapMux?
Read the docs and grab a download at leapmux.dev. The rest of this README covers building and developing LeapMux from source.
Table of Contents
- Architecture
- Prerequisites
- Quick Start
- Development
- Technology Stack
- Project Structure
- Contributing
- License
- Disclaimer
Architecture
LeapMux includes one Go binary (leapmux), a SolidJS frontend, and a Tauri desktop shell.
These parts form three components:
- Frontend — A SolidJS web app that renders the workspace UI. The desktop app embeds the same frontend. Its views include:
- A tiling layout.
- Agents.
- Terminals.
- A file browser.
- Hub — A Go service that manages login and workspaces. It registers workers and supplies an authenticated relay for encrypted Frontend↔Worker traffic. Its storage supports:
- SQLite, the default.
- PostgreSQL.
- MySQL.
- CockroachDB.
- YugabyteDB.
- TiDB.
- Worker — A Go process that keeps its own SQLite database. It connects outbound to the Hub, so it can operate behind a NAT. It runs:
- Agents.
- PTYs.
- File browsing.
- Git operations.
The binary runs in several modes:
| Command | Description |
|---|---|
leapmux solo |
Hub + Worker, single-user; local IPC needs no credential and TCP starts with password setup |
leapmux hub |
Central service only (auth, relay, database) |
leapmux worker |
Connects to a remote Hub |
leapmux dev |
Hub + Worker on all interfaces, login required |
leapmux control admin |
Online, authenticated CLI for users, workers, OAuth, settings, and tokens |
leapmux recover |
Offline break-glass CLI: first-admin bootstrap, password reset, encryption keys, database |
Each mode requires a command. Start an instance with start, which runs it as a service of the operating system and waits until it is ready, and stop it with stop. restart and status act on a running instance. enable configures automatic startup without starting the instance, and disable removes that configuration from a stopped instance. run keeps an instance in the foreground; the container image uses it.
Register a standalone Worker before you start it:
leapmux worker register --hub https://hub.example.com --registration-key YOUR_KEY
leapmux worker start
Solo and dev register their embedded Worker automatically. A fresh dev instance reports ready_for_setup until an administrator completes /setup.
The connections use these protocols:
- Frontend↔Hub uses ConnectRPC.
- Frontend↔Worker uses hybrid post-quantum Noise_NK over one WebSocket that the Hub relays.
- Worker↔Hub uses ConnectRPC for registration and one WebSocket for its stream.
The Hub routes traffic but cannot read Frontend↔Worker content.
The wire format uses Protocol Buffers in /proto/leapmux/v1/.
Each constant that multiple languages share lives once in /contracts/.
The generators produce that constant for Go, TypeScript, and Rust.
LeapMux supports exactly one active Hub process per database. The Hub holds a runtime lease in the database. It refuses to serve when another live Hub owns that lease. A replacement can take over after the owner releases the lease or the lease expires. Administrative CLI processes can access the database while the Hub runs.
For the full architecture, deployment modes, and threat model, see the Concepts and Security & Threat Model chapters at leapmux.dev.
Prerequisites
This README describes how to build and develop LeapMux from source. To use LeapMux, download a desktop app or server build from the releases page. Read the user documentation at leapmux.dev.
Before you begin, ensure you have the following installed:
- Go 1.27.3 or later
- Node.js 26 or later
- Bun 1.4.4 or later - JavaScript runtime and package manager
- Task - Task runner (replaces Make)
- buf CLI - Protocol Buffer code generation (authentication recommended to avoid rate-limit errors)
- protobuf (
protoc) - Protocol Buffer compiler (required by Tauri'sprost-build) - SQLite (usually pre-installed on most systems)
- Docker - Required for building Docker images (on macOS, the project recommends Rancher Desktop)
- dekit - Multi-process runner (required for
task dev,task dev-solo, andtask dev-desktop) - Rust toolchain - For the Tauri desktop app (built by
task build) - Tauri desktop prerequisites - WebView/system packages required by Tauri on your platform
The Go build tools live as tool dependencies in separate modules under tools/:
sqlcgolangci-lintgotestsum
Task builds each tool with its own dependency graph through scripts/run-go-tool.mjs.
The launcher runs the tool in the caller's directory and preserves the application workspace.
The tool modules stay outside go.work.
You do not need to install these tools separately.
Install dekit with its official installation instructions for your operating system.
macOS
Install Bun by following the instructions at https://bun.sh/.
Install the remaining dependencies with Homebrew:
brew install buf go go-task node protobuf rust
To build Docker images, install Rancher Desktop or another Docker-compatible runtime separately. Docker Desktop and OrbStack work also.
Arch Linux
Install the official repository packages with pacman:
sudo pacman -S buf bun go go-task nodejs npm protobuf rust
The Arch go-task package installs the binary as go-task. Add a shell alias so that task works:
# Add to your ~/.bashrc or ~/.zshrc
alias task=go-task
For desktop app builds, install these dependencies:
- The Tauri prerequisites for Arch Linux.
- GStreamer, which
bundleMediaFrameworkincludes in the AppImage. dpkg, whosedpkg-debcommand builds the.debbundle. Arch does not installdpkgby default.
sudo pacman -S webkit2gtk-4.1 libayatana-appindicator librsvg patchelf dpkg \
gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad-libs gst-libav
Windows
Install dependencies with winget:
winget install --id Microsoft.PowerShell --source winget
winget install --id GoLang.Go --source winget
winget install --id OpenJS.NodeJS.LTS --source winget # or OpenJS.NodeJS for the current (non-LTS) release
winget install --id Oven-sh.Bun --source winget
winget install --id Task.Task --source winget
winget install --id bufbuild.buf --source winget
winget install --id SUSE.RancherDesktop --source winget # or any other Docker-compatible runtime (e.g. Docker.DockerDesktop, Podman.Podman)
winget install --id Rustlang.Rust.MSVC --source winget
winget install --id Google.Protobuf --source winget
winget install --id Microsoft.VisualStudio.BuildTools --source winget # or Microsoft.VisualStudio.2022.Community if you prefer the full IDE
After Microsoft.VisualStudio.BuildTools installs, open the Visual Studio Installer.
Enable the "Desktop development with C++" workload in the installation.
Winget installs the bootstrapper but does not select a workload automatically.
For the remaining Tauri Windows prerequisites (WebView2, etc.), see the Tauri Windows prerequisites.
Quick Start
Get LeapMux running locally:
# 1. Clone the repository
git clone https://github.com/leapmux/leapmux.git
cd leapmux
# 2. Generate code and download assets (protobuf, contracts, sqlc, and spinner JSON — not checked into git)
task generate
# 3. Start all services (requires dekit)
task dev
After all services start, open this URL in your browser:
http://localhost:4327
Each dev target generates code and builds its prerequisites.
It then runs dekit mprocs to start the processes concurrently:
| Command | Processes | Description |
|---|---|---|
task dev |
Go backend (leapmux dev run) + Bun frontend dev server |
Full-featured dev mode on all interfaces, login required |
task dev-solo |
Go backend (leapmux solo run) + Bun frontend dev server |
Localhost-only, single-user; the browser sets the first solo password |
task dev-desktop |
Bun frontend dev server + Tauri desktop app | Desktop app development (builds sidecar first) |
Development
Building
Build all components:
task build
Build individual components:
task build-backend # Build leapmux binary (Go)
task build-frontend # Build frontend assets
task build-desktop # Build desktop app for current platform (Tauri v2 + Rust)
The build writes the leapmux binary to the repository root.
Tauri writes desktop bundles under desktop/rust/target/.
The build copies these final artifacts to the repository root also:
- macOS:
.dmg - Linux:
.AppImageand.deb - Windows:
.msiand.exe
Testing
Run all tests except end-to-end (E2E) tests:
task test
Run specific test suites:
task test-backend # Backend tests
task test-frontend # Frontend tests (Vitest)
task test-desktop # Desktop Go sidecar + Tauri Rust shell tests
task test-e2e # End-to-end tests (Playwright)
task test-docker IMAGE=leapmux:latest # Startup and shutdown of a built Docker image
CI runs the complete validation pipeline on Linux amd64.
macOS and Windows run task test-native and the full native build.
Linux arm64 runs task test-native-linux and the full native build.
That target adds Go lint and vet for all three operating systems on arm64.
The native test target runs these checks:
- Go backend tests, except the tests that need Docker
- Go desktop sidecar tests
- Rust desktop tests and Clippy for the host platform
- Frontend script and end-to-end helper tests, including native process and filesystem tests
- The cache snapshot tests against this OS's real toolchains (
task test-cache-native)
Build cache snapshots
CI caches restore through one policy registry, scripts/cache-policy.mjs.
Every archive key embeds the snapshot generation, so an archive that an older
retention rule produced never restores again. The rules that the plan fixes:
- A writer that misses its exact key starts from empty owned roots. It never inherits a fallback snapshot.
- A reader may restore a fallback snapshot from the current generation, but it cannot save the resulting directory.
- An unusable exact hit rebuilds active data. It does not publish over the occupied archive key or request deletion of older archives.
- Dependency archives populate an isolated empty directory from the current declarations, so an inherited obsolete dependency cannot enter an archive.
- Compiled archives trim before publication: the Rust rule keeps the dependency outputs of every profile and the source data that reusing them requires, and removes application binaries, bundles, and incremental data.
- A failed build, test, trim, or export prevents the save. A capacity skip
reports
skipped-capacity, saves nothing, and requests no remote pruning. - The remote pruner deletes older archives only after it verifies the replacement archive under the exact key and branch.
Run the snapshot tests against the real toolchains of this machine:
task test-cache-native
Test APT selection against real installed-package metadata in Linux:
task test-cache-linux
Prove that the Docker cache export reads the current mount, then restore its archive into fresh builders and verify that dependencies do not compile again. The check needs Docker and removes its builders after the run:
task test-docker-cache
The check retains complete command logs under .tmp/docker-cache-check-reports/.
It reports cold-writer and warm-reader durations as observed measurements.
Linux amd64 covers all frontend tests, repository script tests, and schema validation. Both Linux architectures run Go lint and vet checks for all three operating systems. The native jobs retain filesystem, process, interprocess communication, and desktop test coverage.
The native CI jobs verify service registration and removal on every pull request
update and every push to main. The Linux amd64 and arm64, macOS, and Windows jobs
reuse their built CLI for these checks. The tests exercise enable, status, and
repeated disable for Hub, Worker, Solo, and Dev. They also start and stop Solo
through the native service manager and verify local control access restrictions.
Boot cases run on every platform. macOS and Windows also cover login cases.
The macOS job fails if the runner's GUI domain is unavailable. Linux login cases
run when a graphical session is active; headless Linux runners run boot cases only.
Native tests need no Go build tag. Ordinary test runs skip native installation
when no disposable-account fixture is supplied. A supplied fixture must pass all
account and privacy checks. task test-cli-services requires the fixture, so CI
cannot silently skip native verification when its preparation fails.
The CI check creates a private account fixture and removes it after verification.
On Windows, it resets only the disposable runner account password and keeps the
credential in the session credential store. It refuses workstation and self-hosted
execution. Run task test-cli-services with an explicitly prepared disposable
account fixture for native acceptance outside this workflow.
Run specific tests by passing arguments after --:
# Backend tests: -run <regex> <packages>
task test-backend -- -run TestMyFunction ./internal/hub/...
# Frontend unit tests: pass a file path to Vitest
task test-frontend -- src/lib/validate.test.ts
# E2E tests: pass a file path or --grep <pattern> to Playwright
task test-e2e -- tests/e2e/040-chat-message-rendering.spec.ts
task test-e2e -- tests/e2e/pi/text-attachments.spec.ts
task test-e2e -- --grep "repaints the app"
Coding agent coverage
The source checklist lives beside the provider specs under frontend/tests/e2e/feature-matrix/.
Two JSON files define the coverage:
- features.json holds stable feature IDs and precise descriptions. It holds display labels and website publication choices also. It lists the feature groups, and each published feature specifies its group. The website shows the groups in that order, and the published features of a group stand together.
- checklist.json holds each provider and feature combination.
Each entry supplies its distinct spec path and its support state.
It records source verification and browser results separately.
Each entry holds two notes. The user note is one short paragraph with no implementation detail and no raw HTML.
It keeps upstream issue links, and each link is an
https://link. The detail note holds the evidence for the maintainers. The website shows the user note only.
A support state is one of three values:
supported: LeapMux delivers the feature with this agent.agent-limit: the native protocol of the tested agent version cannot carry the feature.leapmux-limit: the native protocol carries the feature, and LeapMux does not use it yet.
A limited cell needs a detail note. A limited cell of a published feature needs a user note also.
A hidden feature has no user note, because the website does not show it.
task validate-json requires each cell to name its own spec and to mark that spec as passed.
Feature IDs use kebab-case and match the spec filenames.
For example, Pi's text-attachments entry points to frontend/tests/e2e/pi/text-attachments.spec.ts.
A pending browser result does not mean that the feature is unsupported.
Mark a browser entry as passed only after its complete spec passes.
Unsupported features need native refusal or limitation assertions also.
Run the affected provider specs with the examples below.
Run task test-scripts to check the source matrix and script behavior.
Run task site to generate the published feature matrix from these same files.
The site includes published features and their descriptions.
The checklist includes additional provider tests that the site does not publish.
E2E execution
Keep provider-specific browser specs directly under frontend/tests/e2e/<provider-name>/.
Keep generic browser specs directly under frontend/tests/e2e/.
Keep shared components under frontend/tests/e2e/helpers/, with their unit tests beside them.
The .spec.ts extension selects Playwright. The .test.ts extension selects Vitest.
Browser tests of a shared helper still belong at the E2E root.
The E2E launcher splits the selected files into isolated Playwright processes. The default process count is the smaller of four and the available CPU capacity. The selected file count limits the actual shard count also. Each process runs one Playwright worker and shares its fixtures across its own tests. Each process owns these resources:
- A LeapMux server and a mock model server.
- A browser context and a shared tab.
- Private provider configuration and databases.
- Private records of the processes that its tests start.
- A private copy of the binary.
- Private reports and test artifacts.
The launcher builds the backend once before any shard starts. It uses the same binary for every shard. No E2E test sends a request to a real model.
Use --workers to select the number of isolated processes:
task test-e2e -- --workers=2
task test-e2e -- --workers=50% tests/e2e/pi/
task test-e2e -- --workers=1 tests/e2e/pi/
The launcher consumes this option.
Every child still uses --workers=1 and zero retries.
The launcher rejects --fully-parallel because tests within a shard share mutable fixtures.
Interactive modes use serial execution. Custom configurations and manually selected shards use serial execution also. Invocation-wide deadlines and failure limits retain serial execution. Snapshot updates and source updates use serial execution also.
Serial and parallel runs retain artifacts under frontend/test-results/runs/<run-id>/.
An explicit --output=<directory> changes the root to <directory>/runs/<run-id>/.
Each run retains its complete console log and test artifacts.
The default configuration retains Playwright's own reports also.
Serial runs preserve the caller's reporter options and explicit report destinations.
For parallel runs, the launcher merges the Playwright blob reports and verifies every selected test case.
The parallel merge preserves each case's project and repeat count also.
Use --reporter to select reporters for the combined parallel result.
Each parallel shard retains its internal list, blob, and JSON reports.
For parallel runs, the launcher prints the combined JSON report path.
Set PLAYWRIGHT_JSON_OUTPUT_FILE to select that report's destination.
Alternatively, set PLAYWRIGHT_JSON_OUTPUT_DIR and PLAYWRIGHT_JSON_OUTPUT_NAME.
The explicit file value takes precedence.
Failed runs retain reports and attachments after the launcher stops the test processes.
Later serial or parallel runs preserve these artifacts.
CI retains test results from passing and failed runs in one compressed test-results-*.tar.gz archive per job.
The filename identifies the job, operating system, architecture, matrix index, and run attempt.
Download the archive directly from the workflow run's Artifacts section within seven days.
Each test command records its complete console output and exit status under .tmp/test-results/.
Bun, Vitest, and Go tests also write JUnit reports there; Rust tests retain their console results.
The archive includes available Playwright reports, attachments, and traces, together with launcher console logs and fixture records.
Launcher integration tests retain fixtures only when their outer test fails, including a cleanup failure after both Playwright cases pass.
Native CI jobs, Docker image checks, and Renovate tests use the same capture script and upload action.
Use --last-failed to run the failed cases from the combined result:
task test-e2e -- --workers=2 tests/e2e/pi/
task test-e2e -- --last-failed
The launcher stores the combined selection, in Playwright's own format, at the output root's .last-run.json.
A complete passing run clears the prior failed selection.
A parallel run that selects no test leaves the saved selection unchanged.
The last-failed run uses parallel execution.
Each shard reads a private copy of the selection through --last-failed-file.
Only the merged result replaces the caller's .last-run.json.
The launcher refuses an absent or malformed selection, because a rerun of the failures must never become a complete run.
An explicit --last-failed-file or PLAYWRIGHT_LAST_RUN_OUTPUT_FILE selects another state file.
If the preceding run used --output=<directory>, use the same option for its last-failed run.
Use --failed-files to run every file that holds a test without a complete clean result:
task test-e2e -- --failed-files
task test-e2e -- --failed-files-from=test-results/runs/<run-id>/report.json
This option reruns complete files, not single cases.
A complete file is the unit of acceptance for a matrix cell.
The launcher reads the last combined report, .last-run-report.json under the output root.
Each parallel run saves that report after its coverage check, also a run that selects only some tests.
A serial run saves no report.
The launcher refuses a report that is older than the last-run state, because a later run replaced the state.
--failed-files-from reads an explicit combined report instead.
It resolves a relative path against the frontend directory, as --output does.
The option selects its own files.
Do not combine it with --last-failed, --test-list, --only-changed, or file arguments.
Do not combine it with --grep, --grep-invert, --test-list-invert, or --shard, because they select fewer tests of a file.
The launcher refuses an absent or malformed report.
The launcher balances the shards by the measured duration of each file.
Each parallel run records the duration of every file in .file-durations.json under the output root.
The next run assigns the files to the shards longest first, from that history.
Without a usable history, the launcher uses Playwright's own --shard=i/N split.
Use --balance=off to select Playwright's own split.
Use --pass-with-no-tests to accept an empty selection.
Without it, a rerun fails before the build when the failed selection lists no test.
Linting
Run all linters:
task lint
Run specific linters:
task lint-versions # Check documented tool versions against versions.env
task validate-json # Validate every project-written JSON file against its schema
task lint-proto # Lint Protocol Buffer definitions
task lint-backend # Lint Go code (hub + worker)
task lint-frontend # Lint frontend code (TypeScript typecheck + ESLint)
task lint-desktop # Lint desktop Go sidecar (golangci-lint) + Tauri Rust shell (clippy)
Auto-fix lint violations:
task lint-fix # Fix all (Go, frontend, desktop)
task lint-fix-backend # Fix Go code (golangci-lint --fix)
task lint-fix-frontend # Fix frontend code (ESLint --fix)
task lint-fix-desktop # Fix desktop Go code + Tauri Rust code (clippy --fix)
Desktop Prerequisites
Desktop builds use Tauri v2:
- macOS: Xcode Command Line Tools, Rust, WebKit (system)
- Linux: Rust plus the WebKitGTK/Tauri native dependencies for your distro (see Tauri Linux prerequisites) and GStreamer (see the Arch Linux section above)
- Windows: Rust MSVC toolchain plus WebView2
Code Generation
Regenerate all generated code and downloaded assets (Protocol Buffers, contracts, sqlc, and spinner JSON):
task generate
You can also run each generator individually:
task generate-proto # Generate Protocol Buffer code (Go and TypeScript)
task generate-contracts # Generate Go/TS/Rust constants from contracts/*.json (the single source for every cross-language value)
task generate-sqlc # Generate type-safe SQL code (hub and worker)
task generate-spinners # Download spinner verb JSON files from awesome-claude-spinners
Task uses checksums to skip generation when source files stay the same.
Run task --force generate to force generation.
Run task generate-proto after you modify .proto files in /proto/leapmux/v1/.
Run task generate-sqlc after you modify SQL queries in these directories:
/backend/internal/hub/store/*/db/queries//backend/internal/worker/db/queries/
Run task generate-contracts after you modify contracts/*.json.
A new proto enum value, such as AgentProvider or Scope, fails generation until its contract entry exists.
Preparation
Prepare every module for builds (code generation, frontend install, asset generation, icon generation, and embedding the frontend into the backend):
task prepare
You can also run each step individually:
task prepare-frontend # Generate proto/contracts/spinners, run bun install, generate icons, copy NOTICE.html
task prepare-backend # Generate proto/contracts/sqlc, build the frontend, and embed it into the backend
task prepare-desktop # Generate proto/contracts, build the frontend, prepare the backend, and generate desktop icons
Build targets run their required preparation steps automatically.
You can run task build without a separate task prepare command.
Third-Party License Notice
Generate NOTICE.md and NOTICE.html with all third-party dependency licenses:
task generate-notice
Run this command after you change dependencies. Regular build targets do not run it. The task fails if a dependency lacks a license file. It fails also if a vendored override's license identifier differs from the upstream package.
Dependency updates with Renovate
The Renovate workflow runs every day at 03:17 Asia/Seoul (17 18 * * * in UTC).
GitHub can start a scheduled run a few hours late. The run creates the same updates at any hour.
Each run creates and maintains routine branches, lockfile maintenance, and security fixes.
renovate.json defines the update groups. Each toolchain or tool pin in versions.env gets its own branch.
- Routine major updates wait for approval in the Dependency Dashboard.
- Security fixes, including major fixes, bypass dashboard approval. Renovate proposes a security fix once the patched version is two hours old. Within those two hours, Renovate stops the whole run when the artifacts of a new security branch fail, so a younger fix waits for the next run.
- Every new dependency version needs a release timestamp and a release age of at least three days.
Required CIrejects a pull request whose lockfiles add a younger version, whoever opens it. To take a younger version, wait until it is old enough, and then run the check again. Renovate already holds a new bun or cargo version to the age while it writes a branch. cargo resolves through a local copy of the crates.io index that leaves out every younger version. A young Go module thatgo mod tidyadds appears only inRequired CI, after Renovate opens the PR. - A security PR may add the advisory's patched version and the versions that it pins exactly, and its PR comments say so.
Only a package that an open Dependabot alert reports, in the lockfile that the alert gives, may take such a fix.
A security PR also takes a new version of a pin in a workflow, and no check covers that pin: a tag records no publication time that its author cannot change.
Check the release date of such a pin before you merge.
versions.envholds no pin that a Dependabot alert can match, and a test enforces this, so a lockfile check covers every such dependency. - Every merge needs a human review and the
Required CIandNOTICEchecks. Renovate never approves or merges a pull request (PR).
The Dependency Dashboard lists the updates and security alerts that Renovate did not propose under Skipped Dependencies, with the reason for each.
A PR description holds only Motivation, Modifications, and Result.
Warnings, security advisories, and release notes go into bot-owned PR comments.
task publish-renovate-details -- --dry-run previews the comments that a publishing run captured.
A dry run renders no PR, so it captures none.
Dependabot alerts supply the vulnerability findings.
Required CI reads the open alerts of a security branch with its job token, which has the vulnerability-alerts: read permission.
Keep the dependency graph and Dependabot alerts enabled.
Keep Dependabot's automatic security-update PRs disabled.
See Renovate's security-update requirements.
.github/renovate/ pins Renovate and its complete dependency tree.
task install-renovate installs it with --frozen-lockfile --ignore-scripts.
On macOS and Linux, it then compiles Renovate's RE2 regular-expression engine from the locked sources.
task lint, task test-scripts, and task test therefore need a C++ compiler and Python 3 there, which node-gyp uses.
Run the Renovate targets with the Node.js and Bun versions in versions.env.
A run fails when it exceeds 50 minutes, or when Renovate cannot finish the repository, for example after a network error.
Each run uploads its logs, timing records, and tool invocation records as the renovate-diagnostics artifact.
Credentials
A repository administrator owns the GitHub App, its credentials, and the activation settings.
The App is registered under the leapmux organization.
Its homepage is the repository URL, and its webhooks are disabled.
Only this account may install it ("Only on this account"), so nobody else can install it on another repository.
It is installed only on leapmux/leapmux, with these repository permissions:
| Permission | Access |
|---|---|
| Contents | Read and write |
| Pull requests | Read and write |
| Issues | Read and write |
| Workflows | Read and write |
| Commit statuses | Read and write |
| Checks | Read-only |
| Administration | Read-only |
| Metadata | Read-only |
| Dependabot alerts | Read-only |
Grant no organization permission and no merge-queue permission. Administration stays read-only, so the App cannot change rulesets.
RENOVATE_APP_PRIVATE_KEY(Actions secret) holds the App's private key.RENOVATE_APP_CLIENT_ID(repository variable) holds the App's Client ID.
Never send a private key or a token through chat, and never commit one.
A dry run uses a read-only installation token.
A publishing run checks the main rules with that token, then requests a separate write token.
Neither token can bypass the rules.
The release workflow pushes its version commits and its tag with RELEASE_ADMIN_TOKEN.
That token is a secret in the release-admin environment.
Create it as a fine-grained personal access token with these settings:
- Resource owner:
leapmux - Repository access: only
leapmux/leapmux - Repository permission: Contents, read and write
- Expiration: 90 days
The environment permits only the main branch and requires approval by trustin, who may approve a release that they dispatched.
Replace the token before it expires.
Approve the environment only for an intentional release. Never dispatch a release to test Renovate.
Protection, suspension, and recovery
An active ruleset on refs/heads/main requires one review, dismisses stale approvals, and requires approval of the latest push by another person.
It also requires Required CI and NOTICE from GitHub Actions (application ID 15368).
Only the repository administrator role may bypass it.
Keep the existing deletion, force-push, and linear-history rules.
GitHub hides bypass actors from App tokens.
An administrator therefore records the verified rulesets in the repository variable RENOVATE_PROTECTION_SNAPSHOT.
A publishing run stops before it requests a write token when the live rules differ from that snapshot.
After any protection change, refresh the snapshot:
mkdir -p .tmp
task snapshot-renovate-protection > .tmp/renovate-protection-snapshot.json
gh variable set RENOVATE_PROTECTION_SNAPSHOT --repo leapmux/leapmux < .tmp/renovate-protection-snapshot.json
The capture command uses your gh authentication and only reads.
It rejects any bypass actor other than repository administrators.
Two repository variables control the workflow:
RENOVATE_ENABLED=trueenables the daily run. Set it tofalseto suspend Renovate.RENOVATE_PUBLISH_READY=truepermits publishing. Set it tofalsealso to block manual publication while you repair credentials or protection.
To resume after a suspension, follow these steps:
Dispatch a dry run:
gh workflow run renovate.yaml --ref main -f mode=dry-runCheck its
renovate-diagnosticsartifact. The queue, including the measured rebases, must finish within 40 minutes. The run measures the rebases only when it proposes a Go workspace update. When.tmp/renovate-rebase-benchmark.jsonreportsskipped, dispatch another dry run after a Go update appears.Set
RENOVATE_PUBLISH_READY=true, then dispatch one publishing run with-f mode=publish.Check the dashboard, the PRs, and CI. Then set
RENOVATE_ENABLED=true.
When an update fails, read the artifact error in its PR and the run's renovate-diagnostics artifact.
Correct the dependency or the generator, then dispatch another dry run.
When a frontend update fails to install, reuse the patch test in frontend/src/test-support/singletonInstalls.test.ts.
Validate the Renovate configuration and scripts locally:
task test-scripts
task test-backend -- ./cmd/leapmux-dependency-imports
task lint-renovate
task renovate-extract
task renovate-extract writes the real dependency inventory to .tmp/renovate-inventory.json, with no credential and no registry lookup.
Before you merge a change to the Renovate scripts, run a full dry run locally.
It runs your local scripts against the live repository, makes only read requests, and publishes nothing.
It uses your existing gh credential, which needs read access to the repository and its Dependabot alerts:
GH_TOKEN="$(gh auth token)" task prepare-renovate
RENOVATE_TOKEN="$(gh auth token)" task renovate-dry-run
When you upgrade Renovate, task test-scripts must pass, because the scripts use internals of the pinned CLI.
Cleaning
Remove all build artifacts and generated code:
task clean
Clean a specific module:
task clean-backend # Remove leapmux binaries and generated/ directories
task clean-frontend # Remove .output, dist, node_modules, and generated/ directories
task clean-desktop # Remove desktop binaries, bundles, the generated contracts module, and Rust target/
Docker images
Build Docker images containing the full LeapMux stack:
# Build both Alpine and Ubuntu images
task docker-build
# Build only Alpine
task docker-build-alpine
# Build only Ubuntu
task docker-build-ubuntu
The default build targets linux/amd64 and linux/arm64.
You can override the platform and tag:
task docker-build-alpine PLATFORM=linux/amd64 TAG=leapmux:dev
The image uses a multi-stage build (buf, Bun, Go). versions.env at the repository root holds the versions of the tools and the base images.
Tool versions
versions.env is the single source of truth for every toolchain and base-image version.
A JavaScript tool is not a toolchain: a lockfile pins it, as frontend/bun.lock pins node-gyp and site/bun.lock pins wrangler.
These consumers read it directly:
Taskfile.yamlloads it throughdotenv:.- The CI workflows write it to
$GITHUB_ENV. docker/Dockerfilereads it as build arguments.
This README and the documentation site cannot use variables for tool versions.
The go directive in each go.mod has the same restriction.
Task generates these values from versions.env:
task sync-versions # rewrite those copies from versions.env
task lint-versions # fail if a copy differs from versions.env (task lint runs this also)
After you edit versions.env, run task sync-versions.
Add a claim to CLAIMS in scripts/sync-versions.mjs when another location states a version.
A claim whose pattern matches nothing fails the build.
This check detects a changed sentence that no longer receives version updates.
Documentation site
The site at leapmux.dev uses Hugo and Hextra.
Its source lives under site/.
Hugo lives as a go tool dependency in site/go.mod.
You do not need to install Hugo separately.
task site # Build the static site into site/public/
task dev-site # Live-reload dev server at http://localhost:1313
Technology Stack
Frontend
- Bun - Runtime and package manager
- ConnectRPC - RPC client for browser
- Noble - Cryptographic primitives for E2EE (X25519, ML-KEM-1024, SLH-DSA, ChaCha20-Poly1305, BLAKE2b)
- Lucide - Icon library
- Milkdown - Markdown editor
- Nitro - Static build output and prerendering
- Oat - Classless CSS framework
- Playwright - End-to-end testing
- Shiki - Syntax highlighting
- Solid DnD - Drag-and-drop support
- SolidJS - Reactive UI framework
- SolidStart - Solid meta-framework (routing, build)
- Vanilla Extract - Type-safe CSS-in-JS
- Vite - Build tool and dev server
- Vitest - Unit testing
- xterm.js - Terminal emulator
Hub (Central Service)
- ConnectRPC - Modern gRPC-compatible RPC framework (Frontend and Worker communication)
- Go - Primary language
- Goose - Database migrations
- coder/websocket - Worker stream
- koanf - Layered configuration (defaults, file, env)
- Protocol Buffers - Service and message definitions
- Pluggable database - SQLite, PostgreSQL, MySQL, CockroachDB, YugabyteDB, or TiDB (see Architecture)
- sqlc - Type-safe SQL code generation (per-backend: SQLite, PostgreSQL, MySQL)
Worker (Agent Wrapper)
- CIRCL - SLH-DSA post-quantum signatures for E2EE channel handling
- Git - Repository info and worktree management
- Go - Primary language
- coder/websocket - Stream to the Hub
- SQLite - Embedded database for agent and terminal state
Desktop
- Tauri v2 - Desktop application framework (Rust + native WebView)
Site (Documentation)
- Hugo - Static site generator for leapmux.dev
- Hextra - Hugo theme, imported as a Hugo module
Build Tools
- buf - Protocol Buffer tooling
- ESLint - TypeScript/JavaScript linting
- golangci-lint - Go linting
- dekit - Multi-process runner for development
- Task - Build orchestration with checksum-based caching
Project Structure
leapmux/
├── backend/ # Go backend: the unified `leapmux` binary (hub + worker)
│ ├── cmd/leapmux/ # Entry point, subcommand routing, recover + control trees
│ └── internal/
│ ├── hub/ # Hub: auth, channel relay, pluggable store, keystore, OAuth
│ └── worker/ # Worker: agents, terminals, file browser, git, E2EE channel
│ └── agent/ # Agent runtime: the neutral API, and one package per provider in providers/
├── contracts/ # Cross-language constant contracts (JSON + sibling JSON Schema), generated into Go/TS/Rust
├── desktop/ # Tauri v2 desktop app (Rust shell + Go sidecar)
├── docker/ # Dockerfile and s6-overlay service definitions
├── frontend/ # SolidJS web app
│ └── src/components/ # UI: chat (with provider plugins), terminal, files, shell
├── icons/ # App and agent-provider SVG icons
├── proto/leapmux/v1/ # Protocol Buffer service and message definitions
├── scripts/ # Build scripts: contracts/proto generation, JSON-schema validation, NOTICE, icons
├── site/ # Hugo + Hextra documentation site (leapmux.dev)
│ └── content/docs/ # The user manual
├── testdata/ # Cross-language conformance corpora (JSON + JSON Schema), replayed by the Go and TS suites
├── go.work # Go workspace (backend + desktop/go)
├── Taskfile.yaml # Build orchestration (go-task.dev)
└── versions.env # Version string and tool/image versions
Contributing
We do not accept code contributions yet because of the license requirements. LeapMux uses FSL-1.1-ALv2, which converts to Apache 2.0 over time. That conversion requires us to hold the rights to every line of code. Without a Contributor License Agreement (CLA), external contributions would require us to obtain each contributor's consent before the conversion. Obtaining consent from every past contributor would be very difficult. We expect to accept external contributions after we prepare a CLA.
Create issues in the meantime. Include a plan from a frontier model if possible. We will review those issues.
License
LeapMux is licensed under the Functional Source License, Version 1.1, Apache 2.0 Future License (FSL-1.1-ALv2).
This means:
- You can use, modify, and distribute the software
- There are certain limitations on competitive use
- The license automatically converts to Apache 2.0 two years after each release is first made available
See the LICENSE file for full details.
Disclaimer
All product names, logos, and trademarks belong to their respective owners. LeapMux has no affiliation, endorsement, or sponsorship from these companies or any other third party:
- Alibaba Cloud
- Amazon Web Services
- Amp Frontier Corporation
- Anomaly
- Anthropic
- Anysphere
- Apple
- Block
- Cline Bot Inc.
- Cognition
- Don Ho
- Earendil
- Factory
- GitHub
- JetBrains
- Kilo Code
- Letta, Inc.
- Microsoft
- Moonshot AI
- OpenAI
- Stencil Labs
- Sublime HQ
- xAI
- Xiaomi
- Z.ai
- Zed Industries
Coding agent icons indicate compatibility only. Editor and IDE icons serve the same purpose. LeapMux reproduces these icons for identification only.