muxin README

项目的 README,来自 github.com/LumaryLabsLLC/muxin。合并为一个 markdown 文件:README.md。

Muxin

Muxin

One app for all your machines, run by you or by your AI agents.
muxin.dev · free and open source (Apache-2.0)

Muxin's overview: each machine, what's running on it, its CPU, memory and disk, and what needs a look.

Point it at the machines you own (a Mac Studio under the desk, a NUC, a Linux box, a few MacBooks, a Windows laptop) and Muxin becomes the hub for all of them:

Agents can also borrow a machine as a work environment: an agent workspace is a persistent folder (optionally a git checkout) on one of your machines where an agent runs commands, edits files and syncs code.

Install

Download the app from the latest release:

Or with Homebrew, on macOS and Linux:

brew install --cask lumarylabsllc/tap/muxin

SHA256SUMS.txt in each release has the files' checksums.

Muxin tells you when a new version is out: the sidebar says so, and About shows how to update the copy you have (with Homebrew or the AUR, or the new file to download). It asks GitHub for the latest release when it opens and twice a day; turn that off in Settings › General › Updates. muxin updates checks from a terminal.

Muxin was called Muxen before 0.5.1. Updating keeps your settings, machines and sessions, and the muxen command still works. On a Mac, the old Muxen app goes to the Trash the first time Muxin opens.

Build from source

git clone https://github.com/LumaryLabsLLC/muxin && cd muxin
cargo build --release --workspace
./target/release/muxin            # opens the window

--workspace also builds Muxin's agent for this computer, which the app sets up on it. For your other machines' platforms, ./scripts/build-agents.sh builds every agent into dist/agents (it needs zig and cargo-zigbuild).

Requirements:

For servers, CI boxes and agent machines there's a headless build with no GUI libraries: just the CLI and the MCP server.

cargo build --release --no-default-features --features recipes

--no-default-features alone also leaves out recipes (muxin recipe, recipe_check and recipe_apply).

There's nothing else to set up. Fonts and icons are compiled into the binary.

To run muxin from a terminal, use Settings › General › Command line › Install, or muxin shell-command install. On macOS it links /usr/local/bin/muxin to the app (macOS asks for your password when that folder needs it), on Linux ~/.local/bin/muxin, and on Windows it adds Muxin's folder to your user PATH. muxen, its name from before, runs it too. muxin shell-command remove takes it out again.

To get a real app with the Muxin icon:

Releases (a notarized DMG, and for Linux and Windows a tarball and an installer each for Intel/AMD and Arm) are built by GitHub Actions from a version tag: see RELEASING.md.

Quick start

muxin --demo                       # explore simulated machines first; nothing real is touched
muxin                              # your machines: starts with this computer in config.toml
muxin add-machine --name "Mac Studio" --host [email protected]
muxin watch acme                   # live runner status and jobs for the acme org
muxin install mac-studio --count 2 # two runners, registered with acme, as services
muxin status

The app

Keyboard: ⌘P goes to any machine, session or desktop by name, and ⇧⌘P (or ⌘P then >) runs any command, including Theme: Choose…, which previews each theme as you move through the list · ⌘1…⌘9 go to your machines · ⌃1…⌃7 overview, jobs, boxes, GitHub, usage, run, schedules (Alt on Linux and Windows) · ⌘J activity · ⌘R check machines · ⇧⌘R sync GitHub · ⌘N add machine · ⌘T new session · ⌘F or / search your machines and sessions · ⌘B sidebar · ⌘[ / ⌘] back / forward · ⇧⌘] / ⇧⌘[ next / previous session · ⌘, settings. Hold ⌘ to see them in the app, and change them in Settings › Keyboard. On Linux and Windows, use Ctrl instead of ⌘. Coming from herdr? Keys like › herdr at the top of Settings › Keyboard uses herdr's keys wherever Muxin does the same thing (a herdr space is a machine here, a tab a session).

Your settings: config.toml

Muxin keeps everything you set in one file, config.toml, in ~/.config/muxin/ (%APPDATA%\muxin\ on Windows), or in $MUXIN_HOME if that's set. Run muxin paths to see where it is. Older versions kept fleet.toml, settings.json and ui.json in ~/.config/muxen/; the first run brings them into config.toml and leaves the old folder as it was.

[[machine]]
name = "Mac Studio"
host = "[email protected]"      # anything `ssh` accepts, or "local" for this computer
runners = ["mac-studio-01", "mac-studio-02"]   # expected runners; missing ones are flagged
# runner_dirs = ["/Volumes/Fast/runners/*"]   # extra places to look (globs)
# shell = "powershell"                          # Windows; auto-detected when omitted
# user = "ci"   port = 2222   ssh_options = ["-i", "~/.ssh/ci"]
# discover = false                              # don't list runners found but not declared
# notes = "Under the desk"
# direct_address = "nas.example.com:47822"      # where a direct connection reaches it (NAT, a forwarded port)
# ignore_warnings = ["low-disk"]                # warnings it's meant to have (a NAS's small system volume)

[[machine]]
name = "StudioNAS"   # no runners: shown under "Other machines"
host = "nas"

A machine that runs on another one is shown under it: a VM or container reached through that machine (ProxyJump to its own address or 127.0.0.1), or at its address on another port. Muxin works this out from ~/.ssh/config, what each machine reports about itself (a VM says so), and the Docker containers that publish the port ssh goes to. When it can't be reached, it says whether the machine it's on is off or its container is stopped, and it can start or stop that container (muxin power win11 on).

Runners installed in the usual places are discovered automatically: ~/actions-runner*, ~/actions-runner/*, ~/runners/*, /opt/actions-runner* and C:\actions-runner\*. A runner is found from its .runner file and its running Runner.Listener / Runner.Worker processes.

GitHub

Watch an org or a repo in Settings, or with muxin watch acme (or acme/api). Muxin then reads live runner status (online, busy) and the queued and running jobs of the most recently pushed repos.

The token comes from MUXEN_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN, or gh auth token. Like gh, Muxin sends those variables only to github.com; for GitHub Enterprise Server it uses GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKEN. Polling uses conditional requests, so unchanged responses don't count against your rate limit.

Reading and registering org runners needs an org admin token with the admin:org scope:

gh auth refresh -h github.com -s admin:org

Repo runners need admin access to the repo. For GitHub Enterprise Server, set the API URL in Settings or run muxin settings --api-url https://HOST/api/v3.

Use it from AI agents

Muxin ships an MCP server. Print setup snippets that point at your binary:

muxin mcp --print-config

Claude Code

claude mcp add muxin -- /path/to/muxin mcp

Codex (~/.codex/config.toml)

[mcp_servers.muxin]
command = "/path/to/muxin"
args = ["mcp"]

Other MCP clients (Claude Desktop, Cursor, …)

{ "mcpServers": { "muxin": { "command": "/path/to/muxin", "args": ["mcp"] } } }

Add "--demo" after "mcp" to let an agent practice on the simulated machines.

The MCP server has these tools:

Tool What it does
status Counts, GitHub state, every machine, and the attention list. Start here.
get_machine One machine's resources, runners and diagnostics, with hints.
list_runners Runners, optionally filtered by machine or state.
list_jobs Queued and running jobs, including which ones no runner can take.
check_machines Runs the read-only machine check over ssh now.
add_machine, remove_machine, rename_machine Edit config.toml. Nothing on the machine changes, except that add_machine connects to it directly once it answers (unless direct: false or Connect directly is off) and remove_machine turns off a direct connection from this app. remove_machine refuses a cloud machine: cloud_destroy deletes its droplet too.
connect_machine Disconnect from a machine (connected: false) or connect again. Its sessions keep running there.
ignore_warning Stop showing one of a machine's warnings by its code (low-disk), or show it again. Saved in config.toml.
machine_ports What's listening on a machine: ports, programs or containers, and web servers' page titles.
machine_processes, process_signal A machine's busiest processes and its GPUs; stop or kill one.
run_on_machines Runs one shell command on several machines at once, with each one's output and exit status.
snippet_list, snippet_save, snippet_delete, snippet_run Your snippets (saved commands, in folders): list, add or change, delete, and run one on several machines.
wake_machine Wakes a machine: one that's asleep through its agent, one that's off with Wake on LAN.
machine_power Powers a machine on or off, or restarts it: a cloud machine, a VM in a Docker container on another of your machines, or any other machine through its own system (off and restart)
vm_options, vm_create, vm_destroy VMs on your machines: Windows (Docker with KVM) or Linux containers, added to your machines.
recipe_check, recipe_apply Which of Muxin's components a machine has (git, Docker, Node.js, languages, agent CLIs); install the missing ones, and update the agent CLIs. See Recipes.
schedule_list, schedule_save, schedule_delete, schedule_run, schedule_log Commands and agent sessions that run on a machine at set times, run there by its own scheduler.
agent_usage What Claude Code and Codex used over the last N days: tokens, requests and cost at API prices, by model and machine.
install_runners Downloads, registers and starts runners on a machine.
runner_action Starts, stops, restarts, updates or removes a runner, or reads its logs.
get_operation, list_operations Progress and output of long operations.
github_scopes Watches or unwatches orgs and repos, with access checks.
get_settings, update_settings Settings.
list_ssh_hosts Hosts to add: your ~/.ssh/config, your Tailscale network, and this network.
list_files, copy_files, cancel_operation Browse a folder on a machine; copy files and folders between machines; stop a copy.
machine_connection, direct_connection How a machine is reached (direct, ssh, which network, Tailscale's view); pair it for direct connections.
desktop_screenshot, desktop_input Look at a machine's screen (or one monitor of it); click, type and scroll there.
desktop_displays, desktop_add_display, desktop_remove_display, desktop_set_display A machine's monitors; add or remove virtual ones, change their resolution or scale.
desktop_windows A machine's apps' windows, to see and use just one (display: "window:<id>").
log_sources, logs_read A machine's logs: its system log, files, containers and services, and their last lines.
machine_services, service_action A machine's services, containers, images and Compose projects (with CPU and memory); start, stop, restart, enable or disable one.
docker_run, docker_pull, compose_action Run a container, pull an image, bring a Compose project up or down (or start, stop, restart one of its services).
compose_project A Compose project's parts: services, ports, what waits for what, networks, volumes, health.
session_list, session_start, session_read, session_send, session_rename, session_stop Agent sessions on the machines.
session_question, session_answer What a session's agent is asking (its options), and pick one.
github_inbox, github_repos, github_repo, github_item, local_checkouts, git_sync, … The user's GitHub, and git checkouts on the machines.
workspace_create, workspace_list, workspace_get Check out a machine as a work environment; see what exists.
workspace_exec Runs a command in a workspace (or starts it in the background).
workspace_read_file, workspace_write_file, workspace_list_files Work with a workspace's files.
workspace_changes, workspace_sync Review the git diff; rsync code to or from your local checkout.
workspace_destroy, workspace_allow Clean up; turn workspaces on or off for a machine.

Every tool returns structured JSON. Failures come back with a code an agent can branch on:

Many failures also include a hint with the exact command that fixes them. AGENTS.md has guidance written for agents.

Agent skill

Agents that load skills (Claude Code, Codex, OpenCode, Gemini CLI, Pi, Hermes, …) can learn Muxin's CLI from the skill in skills/muxin, with no MCP server to set up. It has the ground rules (start with muxin status --json, confirm before changing things, pass hints on verbatim) and how to work with sessions, boxes, workspaces, runners, machines, cloud machines and VMs. Ask your agent to "review PR 142 in my session on beelink" and it knows what to run.

muxin skill install                   # for every agent found on this computer
muxin skill install --agent hermes    # just one: claude, codex, opencode, gemini, pi, hermes, copilot, cursor, qwen, droid, kimi, or agents
muxin skill install --dir ~/my-agent/skills
muxin skill remove
muxin skill show                      # the guide the skill reads

What muxin skill install puts in place is a short stub: the skill's description, and a line that tells the agent to run muxin skill show. The guide comes from the Muxin you have, so it's never out of date, even after an update. Copies that an older Muxin wrote in full are replaced with the stub when you run muxin skill install again. It goes in ~/.claude/skills/muxin, ~/.config/opencode/skills/muxin, ~/.gemini/skills/muxin, ~/.pi/agent/skills/muxin, ~/.hermes/skills/muxin, or the shared ~/.agents/skills/muxin for Codex, Copilot CLI, Cursor Agent, Qwen Code, Droid and Kimi Code (and agents, for any other agent that reads it).

To follow this repository instead, copy or link the folder into your agent's skills folder (muxin skill install leaves a link alone):

ln -s "$PWD/skills/muxin" ~/.claude/skills/muxin

The CLI, for scripts and agents without MCP

Every command takes --json. In that mode stdout carries JSON only, and errors are printed as {"error": {...}}. Progress and logs go to stderr. Exit codes:

Commands that start long work (installing runners, copying files, making a VM, a cloud machine or a box) wait until it's done and print its log as it goes. The command's own process does the work, so there is no --no-wait: to get your prompt back, run the command in your shell's background (muxin cp … &). install and runner take --timeout <seconds> to give up sooner; the work stops there, and the command says so and exits 1.

muxin status [--refresh]                 # overview + what needs attention
muxin machines | machine <id>
muxin runners [--machine <id>] [--state offline]
muxin jobs
muxin add-machine --name <name> --host <ssh-host> [--no-check]
muxin remove-machine <id>
muxin rename-machine <id> <new name>      # the id stays the same
muxin ports beelink                       # what's listening there (web servers first)
muxin forward beelink 3000                # its port 3000 at localhost:3000 here, until Ctrl-C
muxin run --on beelink,mac-studio -- df -h /   # one command on several machines (--all: every one online)
muxin snippet add "Disk space" --folder Checks -- df -h /   # save a snippet (ls, rm, run --on a,b too)
muxin ps beelink [-n 20]                  # its busiest processes and its GPUs
muxin kill beelink 4242 [--force]         # stop a process (--force: SIGKILL)
muxin wake beelink                        # wake it: through its agent when it's asleep, else Wake on LAN
muxin power win11 off                     # shut a machine down (or restart it); a VM or cloud machine also turns on
muxin vm create win-test --system windows-11 --on beelink   # a VM on one of your machines
muxin recipe check beelink [claude]       # which of Muxin's components it has (git, docker, node, claude, ...)
muxin recipe apply beelink gh claude [--update]   # install the missing ones (--update: and update the agent CLIs)
muxin schedule add beelink --name Tests --every day --at 09:00 --command "make test"
muxin usage [--days 30] [beelink]             # what the agents used, and the cost at API prices
muxin edit beelink:~/code/api [--editor zed] [--print]   # open a folder there in your editor
muxin disconnect <id>                     # stop connecting to it (its sessions go on there)
muxin connect <id>                        # connect again, and check it
muxin ignore <id> low-disk [--undo]       # stop showing one of its warnings (--undo: show it again)
muxin install <machine-id> [--scope acme] [--count N | --name a --name b] [--label gpu] [--mode auto|service|background|docker] [--image IMAGE] [--docker-socket] [--timeout SECONDS]
muxin runner <start|stop|restart|logs|remove> <runner-id> [--delete-files] [--timeout SECONDS]
muxin watch <org|owner/repo>... / unwatch ...
muxin settings [--poll 20] [--scan-repos 10] [--check-interval 15]
muxin ssh-hosts                          # ~/.ssh/config, your tailnet, and this network
muxin files <machine>[:<folder>]         # what's in a folder (alias: ls)
muxin cp <machine>:<path>... <machine>:<folder>   # copy between machines
muxin connection <machine> [--direct on|off]
muxin ipad pair [--machine <machine>]... # pair an iPad: a QR code to scan (ls, rm <name>)
muxin check [--json]                     # one-shot full report
muxin workspace …                        # agent workspaces, see below (alias: ws)

Ids:

Every command also accepts --demo.

The window, the CLI and MCP servers can all run at once. They share the files in the config directory and pick up each other's changes: settings, edits to config.toml, and newer machine checks.

Agent workspaces

A place on your machines for an agent you're using elsewhere (Claude Code on your laptop, say). The agent asks for a workspace and gets a persistent folder on one of your machines, optionally with a repo cloned at a branch or ref. It then works there like it would on a remote dev box. Nothing works there on its own: to hand a task to an agent that works by itself, use a box.

Host or Docker. By default commands run directly on the machine. With isolation: "docker" (CLI --docker), each workspace gets its own fresh container instead, from an image the agent picks (node:22, python:3.13, rust:1, …; default buildpack-deps:bookworm). The workspace folder is mounted at /workspace, the container runs as the ssh user so files aren't root-owned, and a container that disappears (reboot, docker system prune) is recreated on the next command with the files intact. docker_socket shares the machine's Docker for docker-in-docker; that's root-equivalent, so only use it when the task needs it. Docker workspaces need Docker on the machine and the ssh user in the docker group. They aren't available on Windows machines yet.

A worktree of a checkout. When the repository is already checked out on the machine, a workspace can be a git worktree of that checkout instead of a clone (worktree_of, CLI --worktree-of): its own folder and branch, sharing the checkout's history, so it's ready in a moment and several agents can work on one repository side by side. New sessions offer it too (Where › New worktree), and so does handing an issue to an agent when there's a checkout of its repository. Deleting the workspace removes the worktree and keeps its branch; once the branch's pull request is merged, the workspace's card offers to clean it up. (A worktree's git history lives in the checkout's .git folder, so an agent with a sandbox, such as Codex, asks before it commits there.)

The machine can be named, or picked for you: the least-loaded online machine that allows workspaces, optionally matching a platform such as linux or darwin-arm64. Private GitHub repos are cloned with your gh login; the token is passed through the environment for that one command and never written to disk or logs.

Every command an agent runs is recorded with its exit code, duration and the end of its output. You can see that history in the app (Boxes › Agents' workspaces, or a machine's page), or open a terminal in any workspace with muxin workspace shell <id>.

muxin ws create --platform linux --repo acme/api --ref main
muxin ws create --docker --image node:22 --repo acme/web   # an isolated container
muxin ws create --machine beelink --worktree-of ~/code/api --branch fix-login   # a worktree of a checkout there
muxin ws exec ws-7f3a2c -- cargo test          # exits with the command's exit code
muxin ws exec ws-7f3a2c --background -- npm run dev
muxin ws cat ws-7f3a2c .muxen/logs/1.log
echo 'hello' | muxin ws write ws-7f3a2c notes.txt
muxin ws files ws-7f3a2c src --depth 1
muxin ws changes ws-7f3a2c
muxin ws sync ws-7f3a2c ~/code/api --push      # or --pull, add --delete to mirror deletions
muxin ws shell ws-7f3a2c                       # an interactive shell in the workspace, for you
muxin ws ls
muxin ws rm ws-7f3a2c [--keep-files]
muxin ws allow studionas --off                 # forbid workspaces on a machine

ws exec passes the command's stdout and stderr through and exits with its exit code (124 if it timed out), so it composes in scripts. With --json it prints the full result instead.

Safety. Host workspace commands run as the ssh user on your machine, with that user's permissions; they aren't sandboxed. Use Docker isolation for code you don't trust. Workspaces are on by default for every machine with a host. Turn them off per machine with workspaces = false in config.toml, the toggle on the machine's page in the app, or muxin workspace allow <machine> --off. Nothing is deleted automatically: workspaces stay until you or an agent destroys them. Folders live under ~/muxen/workspaces/<id> on each machine (workspace_root in config.toml changes that).

Your GitHub, and handing issues to agents

The GitHub page is built for the loop of picking an issue, handing it to an agent, and moving on:

Muxin uses the GitHub CLI's login (gh auth login) or GITHUB_TOKEN. Settings has a Sign in with GitHub button that runs the CLI's browser sign-in; each machine's page shows whether its own gh is signed in (agents there use it for issues and pull requests) and can sign it in too.

Git on each machine. A machine's page has a Git card: whether its GitHub CLI is signed in, who commits there, and how pushes reach GitHub. When something's missing, one click fixes it: Use my GitHub identity sets git's name and email to your GitHub name and private noreply address, and Use the GitHub CLI runs gh auth setup-git so pushes use the machine's gh login. Agents working there can then commit and push.

muxin git status beelink
muxin git setup beelink --identity --credentials

Permissions. Watching an organization's runners needs the admin:org permission on your GitHub login. Settings shows when it's missing, with a Grant access button that runs gh auth refresh -s admin:org in a terminal (it finishes in your browser), and lists your organizations so watching one is a click.

More than one account. Click your name at the top of the GitHub page to switch. The menu lists every account the GitHub CLI here is signed in to, plus each machine's own gh login: with a work laptop signed in to your work account, pick "@you-at-work · Work MacBook" and Muxin sees that account's repositories, inbox and runners (the token is fetched over ssh when needed and kept in memory only). Work on it with an agent then prefers checkouts on that machine. Switching doesn't change which account gh uses in your terminal. "Add another account…" runs gh auth login.

muxin github inbox                         # what needs you
muxin github repos                         # favorites first (★)
muxin github favorite ZenNotes/zennotes    # --remove to unstar
muxin github accounts
muxin github use work-login                # or: --machine work-macbook
muxin github repo ZenNotes/zennotes        # issues, PRs, runs, and where it's checked out
muxin github issue ZenNotes/zennotes#632   # or the issue's URL
muxin checkouts --repo ZenNotes/zennotes
muxin checkouts --machine beelink --path ~/code/api --git pull

Agent sessions

Start an AI agent on one of your machines and come back to it whenever you like, from the app, from your own terminal, or through another agent.

muxin session ls                                   # every session, and which agents each machine has
muxin session start beelink claude --cwd ~/code/api --prompt "fix the failing test"
muxin session read beelink/claude-3f9a             # what's on its screen
muxin session send beelink/claude-3f9a "yes"       # type, then Enter (--no-enter to skip it)
muxin session do beelink/claude-3f9a pull_request  # an action: commit, commit_push, pull_request, review, fix_comments, conflicts, recap
muxin session question beelink/claude-3f9a         # what it's asking, and the options' keys
muxin session answer beelink/claude-3f9a 1         # pick one
muxin session attach beelink/claude-3f9a           # open it in this terminal; detach with Ctrl-] then d
muxin session restart beelink/claude-3f9a
muxin session rename beelink/claude-3f9a "API server"   # "" goes back to the original title
muxin session handoff beelink/claude-3f9a codex    # Codex takes over, with a note of the work so far (--keep keeps the old one)
muxin session handoff box-7k2m9q gemini            # a box changes agents
muxin session handoff this-mac/claude-3f9a codex --on beelink   # the work moves to beelink, and Codex picks it up there
muxin session stop beelink/claude-3f9a

Build the agent for every platform with scripts/build-agents.sh (needs cargo-zigbuild and Zig for the Linux builds); scripts/bundle-macos.sh runs it and ships the builds inside the app.

Boxes

Hand a task to an agent and let it work on it by itself, on your own hardware. A box is one task: a fresh checkout of a repository on a new branch, in a Docker container of its own on one of your machines, with an agent CLI working in it.

muxin box new acme/api "Add rate limit headers to every response, with tests, and open a pull request"
muxin box new acme/api "Fix the flaky webhook test" --agent codex --on beelink
muxin box new ~/code/app "Finish this refactor" --on beelink     # a checkout there, with its uncommitted work
muxin box ls                                  # every box: working, waiting, idle or paused, and its git
muxin box send box-7k2m9q "Also update the API docs"   # starts it again if it's paused
muxin box attach box-7k2m9q                   # its agent, in this terminal
muxin box shell box-7k2m9q                    # a shell in the box, in this terminal
muxin box pause box-7k2m9q
muxin box rm box-7k2m9q

Agents use box_create, box_list, box_send, box_pause and box_destroy; session_read works on a running box's session.

Sharing a session or a machine

Show someone a session, or a whole machine, straight from your computer. They join from Muxin or from any browser; nothing to install.

To introduce them through a server of your own instead (share-server/ in this repository), set [settings.share] server = "https://share.example.com" in config.toml.

Connections and desktops

Muxin first reaches a machine with ssh, installs its small agent there, and from then on talks to that agent over one live connection instead of a new ssh connection per request: requests take milliseconds instead of ~0.4 s, terminals open instantly, and the sidebar updates the moment a session changes.

iPads. Muxin for iPad reaches your machines directly too, with a key of its own. Add a machine on the iPad by its address (it signs in once with an ssh client of its own, installs the agent and sets up the direct connection), or pair it from here. Pair one in Settings › iPads › Pair an iPad: the iPad scans the QR code that shows (or you paste its link), both show the same six digits, and you click Allow. Each machine you picked then trusts the iPad's key, and the iPad gets their addresses; your Mac isn't needed after that. Unpair takes the key off those machines again, and an iPad connected at the time is let go within seconds. With Alerts on in the iPad's settings, each machine tells the iPad when an agent there is waiting for you, rang the bell, or exited with an error, even while the app is closed: encrypted on the machine with the iPad's own key, through muxin.dev to Apple's push service, which can't read it. From a terminal: muxin ipad pair, muxin ipad ls and muxin ipad rm <name>.

Servers. A machine's page lists what's listening there: web servers first, with their page's title (a dev server, a Docker container's site), then its other ports. Open puts one on this computer at localhost (the same port number when it's free) and opens it in your browser; no desktop needed. Each connection goes through the machine's live connection, so it works over ssh or direct alike, even for servers that listen only on the machine itself. Open ports are listed under their machine in the sidebar (click to open, × to close) and come back when Muxin starts. Open a port takes any port number. From a terminal: muxin ports <machine> and muxin forward <machine> <port>.

Desktop. On a Linux machine with an X11 desktop, a Mac, or a Windows PC someone is signed in to, Show desktop (on its page, or its right-click menu) shows its screen live and sends your mouse and keyboard to it. On Linux ⌘ works as Ctrl; on a Mac it stays ⌘. Keys type what your keyboard puts on them, whatever the machine's own keyboard is: Shift+2 is @ from a US keyboard and " from a German one, even on a machine set to another layout. From a Mac, so does Option (@ on a German one); it's still Alt for keys that aren't characters (Alt+Tab, Alt+F4) and with the mouse, and on US-style keyboards it's always Alt. An open desktop is listed under its machine in the sidebar (and keeps streaming while you look elsewhere); close it there.

Nobody signed in. Muxin shows the screen of the account it connects as, so that account has to be signed in there. Servers often have nobody signed in, and a Remote Desktop window closed without signing out leaves a session with no screen. Muxin says so right away and offers Open with Remote Desktop (Windows), Open with Screen Sharing (Mac) or Open with RDP or VNC (Linux); the machine's right-click menu has it too. It opens the machine's own remote desktop in your app for it: Windows App or Remote Desktop Connection, Screen Sharing, Remmina or FreeRDP. That shows the sign-in screen, so you can sign in. It goes through Muxin's connection to the machine, so it works away from home too and nothing has to be opened in a firewall. Here it's at localhost:3390 (VNC: localhost:5901), listed under Servers. The machine needs it turned on:

From a terminal: muxin desktop rdp <machine> or muxin desktop vnc <machine>.

Monitors, real and virtual. A machine with more than one monitor gets a picker above its desktop: show one monitor at a time (on Linux, or all of them). Add monitor (or Add virtual monitor… in the machine's right-click menu) plugs in a monitor that isn't there, the way DeskPad does on a Mac: pick a name and a size (720p to 4K), and it joins the desktop like a real one, to the right of the others. Windows move onto it, the machine's own tools (System Settings, RustDesk) see it, and while the machine's desktop is open, Muxin lists it under the Desktop item in the sidebar to open it directly. It starts at the main monitor's size and offers every common one (720p to 4K). Above a monitor, pick its resolution, and on Linux desktops that offer it, its scale: 200% makes things twice as big and just as sharp, so a 4K monitor reads like 1080p (the stream is always the screen's own size, so it stays crisp). Right-click a monitor (in the picker or the sidebar) to rename or remove it, and in the all-screens view, click a monitor's name to open it. On Cinnamon each virtual monitor gets copies of the main monitor's panels (menu, clock, dock with the same pinned apps), so it's usable on its own. It stays until you remove it (Remove monitor) or the machine restarts. Handy on a machine with no screen (a dummy HDMI plug, a server), or to give an agent a monitor of its own. On a Mac it's a CGVirtualDisplay. On Linux (X11) it's a software dummy plug: Muxin plugs a made-up monitor (at the size you picked) into a video output with nothing connected, and the desktop sets it up like a real one. That takes root, so when sudo wants a password Muxin asks for yours, only then, sends it to sudo over its encrypted connection, and keeps it in memory only until you quit. Nothing is installed.

muxin desktop displays beelink                     # its monitors (virtual ones marked)
muxin desktop add beelink --size 2560x1440         # another monitor, "Display 2"
muxin desktop shot beelink --display DisplayPort-0 # a screenshot of just that one
muxin desktop set beelink HDMI-A-0 --size 3840x2160 --scale 2  # 4K, things twice as big
muxin desktop remove beelink DisplayPort-0

Apps in windows of their own. Above a machine's desktop, Apps lists the apps open there (Windows, Macs, and Linux on X11). Pick one, and it opens here as a window of its own, at its size there, with nothing around it but its own title bar: drag that to move the window, double-click it to zoom. The pointer takes the app's shapes (a text cursor over text, a hand over links). Click and type as usual: the app comes to the front there first, so keys never land in another app. Resize either window and the other follows; minimize or close the app there and its window here does the same. Once the picture is still, it's sent again sharp. While nothing covers the app there, its menus and dialogs show too. On a Mac, an app's menus stay in the menu bar there.

muxin desktop windows win11                        # its apps' windows
muxin desktop shot win11 --display window:1312130  # a screenshot of just one
muxin connection beelink                  # how it's reached, and how fast
muxin connection beelink --direct on      # pair and connect directly
muxin desktop shot beelink -o screen.jpg
muxin desktop input beelink '[{"type":"click","x":100,"y":200},{"type":"text","text":"hello"}]'

AI agents get the same: machine_connection, direct_connection, desktop_screenshot (an image they can look at) and desktop_input.

When the connection drops (another network, a hiccup, the machine's agent restarting), terminals and the desktop pick themselves back up ("Reconnecting…") instead of stopping. A machine that's shut down is noticed within seconds and shown as offline; a Mac that goes to sleep says so first, and shows as asleep.

Tailscale and moving between networks

If Tailscale is on your Mac, Muxin uses it to keep machines reachable away from home, with nothing to set up: it only reads Tailscale's status and never changes its settings.

Logs

A machine's logs, live: Logs on its page (or right-click it, or ⌘P › Logs) opens them, and they stay under the machine in the sidebar until you close them.

muxin logs beelink --list                          # what there is
muxin logs beelink --unit nginx -n 100             # a service's last lines
muxin logs beelink --file '~/app/storage/logs/laravel.log' --grep error
muxin logs beelink --container postgres --follow   # keep printing (Ctrl-C to stop)

If Muxin itself crashes, it writes what happened to crash.log in its config folder (~/.config/muxin, or %APPDATA%\muxin on Windows). The agent on a machine writes to ~/.muxen/crash.log.

Services and containers

A machine's services, and its Docker containers: Services on its page (or right-click it, or ⌘P › Services). Failed ones come first, then running ones; Find narrows the list.

muxin services beelink                             # services and containers
muxin services beelink restart nginx
muxin services beelink stop postgres --container

Files and the clipboard

Copying files. Copy files on a machine's page (or its right-click menu) opens two panes: the machine with the files on the left, where they go on the right, each a folder you can browse. Pick files and folders, pick a folder, copy. Dropping files from the Finder onto a machine in the sidebar opens it ready to send them there.

muxin files beelink:~/build
muxin cp beelink:~/build/app.tar.gz adibs-macbook-pro:~/Downloads
muxin cp adibs-macbook-pro:~/Projects/site beelink:~/www    # waits until it's copied, with progress

Shared clipboard. Turn it on in Settings › Clipboard. Text you copy on your Mac can then be pasted on your Linux desktops, Windows PCs and other Macs, and what you copy there lands on your Mac (and on the other machines). Passwords copied from password managers (marked private on the clipboard) aren't shared. Neither is text a program in a terminal copies. One exception: the app on Linux can't tell which copies on its own computer are passwords.

Cloud machines

Need a machine you don't have? Muxin can make one in your DigitalOcean account. Connect in Settings › Cloud with an API token (kept in the macOS Keychain), the browser sign-in, or doctl's login. Then pick New cloud machine… in the Add machine dialog: a name, a region (the nearest is preselected) and a size with its price. Muxin creates the droplet with your user and SSH key, installs what you chose (Docker, git and the GitHub CLI; Node with Claude Code and Codex; Tailscale), and adds it to your machines. Then it's like any other machine: terminals, agent sessions, files, workspaces.

A new machine is in your list from the moment DigitalOcean makes it, shown as starting until it has an address (a minute or so). It's billed from that moment, so Muxin never has one it doesn't show: if Muxin is quit or crashes while it's being created, or the droplet takes longer to start than the six minutes Muxin waits, it stays in your machines, Usage and cost counts it, and Destroy deletes it. Muxin fills in its address at a machine check once it has started (what you picked to install isn't installed then: add it from the machine's page). One that still hasn't started after ten minutes is listed under what needs attention.

Sometimes DigitalOcean's answer to the request is lost: it doesn't come in time, or it's an error of DigitalOcean's own. The droplet may have been made all the same. Muxin then looks for it by name, for up to about three minutes, until it's sure: either the droplet is there and goes into your machines, or none was made and nothing is billed. It tells the droplet it asked for by its name, region and size and by when DigitalOcean made it, so one you made by hand under the same name at another time isn't taken for it. If Muxin can't find out (DigitalOcean can't be asked, or two droplets of that name were made in the same minute), what it asked for is listed under what needs attention, with why, until a machine check settles it.

A machine whose droplet you deleted at DigitalOcean says so: Destroy takes it out of your machines. muxin remove-machine (and the remove_machine tool) refuse a cloud machine, because its droplet would stay billed with nothing listing it: destroy it instead.

DigitalOcean bills a droplet by the second while it exists, powered on or off, up to its monthly price; only destroying it stops the charges. Each cloud machine's page shows its rate, what it has cost this month and since it was created, and what this month comes to if you keep it, with Power on/off and Destroy. Settings › Cloud › Usage and cost adds them up: what you're paying per hour now, this month so far (machines destroyed this month included), the month's total if nothing changes, and your whole DigitalOcean bill this month (when Muxin may read it: sign in again in the browser, or use a token with billing:read). Settings › Cloud also says what happens when one sits idle: nothing, a reminder, power off, or destroy, after the hours you choose.

pbpaste | muxin cloud login --token -   # the token on stdin, not in your shell history
muxin cloud options
muxin cloud create dev-1 --size s-2vcpu-4gb
muxin cloud usage                     # what they cost
muxin cloud destroy dev-1

VMs on your machines

Need a clean Windows to try an installer, or a throwaway Linux? New VM… (in the Add machine dialog, the command palette, or a machine's right-click menu) makes one on a machine you already have:

It joins your machines under the one it runs on, with Muxin's agent: sessions, files, the desktop and workspaces work like anywhere, and a UDP port on its host is forwarded to it, so Connect directly works too. Stop and Start it from its page; Destroy deletes its container and disk. Your AI agents can do the same through MCP: make a Windows VM for a test, use it, destroy it.

muxin vm options                                   # where VMs can run, and what
muxin vm create win-test --system windows-11 --on beelink
muxin vm create scratch --system ubuntu-24.04       # on the machine with the most free memory
muxin power win-test off
muxin vm destroy win-test

Recipes

Which tools does a machine have, and can Muxin put the missing ones there? A component is one thing a machine can have: git, Docker, Node.js, a language, an agent CLI. Each one has a check that says whether it's there, an install step, sometimes an update step, the components it requires, the systems it works on, and whether its steps need root. A recipe is a list of components: the ids you name on the command line, or one you saved under a name in the app. Muxin has 22 components built in:

In the app, a machine's page has a Components card, under Git:

From a terminal and for agents, the same things are check and apply:

muxin recipe check beelink                         # all 22: present, missing or unsupported
muxin recipe check beelink claude                  # Node.js, then Claude Code
muxin recipe apply beelink gh claude               # install what's missing, requirements first
muxin recipe apply beelink claude codex --update   # and update the agent CLIs that are behind

Your AI agents have the same through MCP: recipe_check and recipe_apply. Saved recipes are the app's: the CLI and agents name components by id. The components are the TOML files in src/recipe/components, built into the binary.

Schedules

A schedule runs a command, or starts an agent session, on one of your machines at set times: every few minutes, every hour, every day, weekdays, or some days of the week, in that machine's own time. It's kept on the machine and run by its own scheduler (cron, launchd or Task Scheduler), so it runs even when Muxin isn't open. The Schedules page lists them with their last run, runs one now, pauses one, and shows each run's output. An agent schedule ("every morning, go through new issues") starts a session you find under the machine, waiting for you.

muxin schedule add beelink --name "Disk report" --every weekdays --at 09:00 --command "df -h /"
muxin schedule add beelink --name Triage --every day --at 08:30 --agent claude --prompt "Label new issues in acme/api"
muxin schedule ls
muxin schedule log beelink s-ab12cd

How checks and installs work

Windows

Windows machines are managed like the others, over OpenSSH (Settings › System › Optional features › OpenSSH Server, then key-based login; an administrator account for services and runners). Muxin installs its agent in %USERPROFILE%\.muxen\bin and works with PowerShell or cmd as sshd's shell:

Not yet on Windows: Docker runners and Docker workspaces, adding virtual monitors.

The app on Windows is built on Windows (GPUI compiles its shaders with the Windows SDK's fxc.exe): install Rust and Visual Studio's C++ build tools with the Windows SDK, run scripts/build-agents.sh on a Mac or Linux (it makes the Windows agent too, with cargo-zigbuild), then scripts\package-windows.ps1 on Windows. That makes dist\Muxin-<version>-windows-x64-setup.exe (arm64 on Windows on Arm: an installer, with Inno Setup: for this user, no administrator needed, a Start menu entry, optionally muxin on the PATH, an uninstaller) and dist\Muxin-<version>-windows-x64.zip (muxin.exe and its agents\). Started from Explorer it shows no console window; from a terminal it's the same CLI as elsewhere. Secrets go in Windows' Credential Manager.

Develop

cargo test                 # unit + demo-mode integration tests
cargo run -- --demo        # the window, simulated machines
cargo run -- status --demo --json

Source layout:

Cargo.lock pins libc to 0.2.189: GPUI's HTTP client pulls in xattr 0.2, which doesn't build on Linux against newer libc releases. Don't run a blanket cargo update without rebuilding on Linux.

Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md. To report a security problem, see SECURITY.md instead of opening an issue.

License

Muxin is open source under the Apache License 2.0, copyright 2026 Lumary Labs LLC (see NOTICE). The Muxin name and logo are Lumary Labs' trademarks; the license doesn't cover them.

It includes third-party components under their own licenses, listed in THIRD_PARTY_NOTICES.md: the Geist fonts (SIL Open Font License, assets/fonts/OFL.txt), the Lucide icons (ISC, assets/icons/LICENSE.txt), the Phosphor, Hugeicons and Fluent icons (MIT), the MingCute icons (Apache-2.0) and the Solar icons (CC BY 4.0), with their licenses in assets/icons/, GPUI (Apache-2.0) and the Rust crates in Cargo.lock.

muxin (LumaryLabsLLC/muxin)

正在搜索数据库…

467 ·GitHub
这是什么?Muxin 是一款桌面中枢应用,让你可以在一个地方统一管理所有 Mac、Linux 和 Windows 机器上的 AI Agent 会话、远程桌面、文件、日志和 GitHub,并通过 MCP 服务器把同样的功能开放给 AI Agent。
这是桌面应用还是命令行工具?它是使用 GPUI 构建的原生桌面应用(GPUI 就是 Zed 编辑器背后同样的 GPU 加速框架),同时也提供命令行命令,并附带一个只包含命令行和 MCP 服务器的无界面版本,适用于没有图形界面的服务器。
怎么安装并运行?请从最新的 GitHub 发布页面下载适合你操作系统的预编译应用(macOS 为 DMG,Linux 为 deb/rpm/AppImage/tar.gz,Windows 为安装程序),或通过 Homebrew 安装,然后按 Cmd/Ctrl+N 添加它从你的 SSH 配置、Tailscale 网络或局域网中发现的机器。
使用前我需要先配置好 SSH 密钥或 Tailscale 吗?首次连接机器时使用的是你系统自带的 ssh,因此你现有的密钥、ssh-agent 和 ~/.ssh/config 中的别名可以直接生效;之后 Muxin 自带的小型代理程序会接管,可以直接连接,也可以通过 Tailscale 连接,GitHub 相关功能则使用你的 gh 登录状态。
安装时有哪些需要注意的坑吗?Windows 安装程序尚未签名,因此 Windows 会弹出“Windows 已保护你的电脑”的警告,需要点击通过;Linux 版本需要 glibc 2.35+(Ubuntu 22.04、Debian 12 或更新版本)。
我可以为哪些编程 Agent 运行会话?Claude Code、Codex、OpenCode、Gemini CLI、Amp、Pi,或普通的 shell,每个都运行在真实的终端中,即使关闭应用后也会继续运行。
AI Agent 也能自己使用 Muxin 吗,而不只是我?可以。所有功能都以 MCP 服务器(muxin mcp)以及可脚本化的 --json 命令形式开放,因此 Claude Code、Codex 等 Agent 可以直接检查你的机器并修复问题。
它能统计我的 AI 用量花了多少钱吗?Usage 视图会读取 Claude Code 和 Codex 自身的日志,按日期、模型、机器和文件夹显示 token 和请求数,并按 Anthropic 与 OpenAI 的 API 标准价格估算这些用量对应的费用。
这个应用以前叫什么名字?它在 0.5.1 版本之前名为 Muxen;更新后所有设置、机器和会话都会保留,旧的“muxen”命令仍然可以使用。
有哪些类似的项目?navop, Codync, tusk, shipyard, coral, xpipe, nyaterm, webcodex
大小
12 MB
星标
467
时长
1个月
提交 · 90 天