Command line

The muxen command does what the app does, from a terminal. It’s the same program: run with no arguments, it opens the window. Use it for quick looks, in scripts, and for AI agents that run shell commands but don’t speak MCP.

Install the command

• macOS: Settings › General › Command line installs it in /usr/local/bin.
• Windows: the installer offers to add it to your PATH.
• Linux: muxen shell-command install puts it in ~/.local/bin.

muxen shell-command remove takes it out again. muxen --help, and --help after any command, lists the options.

JSON and exit codes

• --json, on every command: print JSON only on stdout, the same shapes the MCP tools return. Errors print as {"error": {...}} with a code and often a hint. Progress goes to stderr.

Exit code	Means
0	Success.
1	The operation failed.
2	Bad input, or the thing wasn’t found.

muxen ws exec is the exception: it exits with the command’s own exit code (124 if it timed out), so it composes like running the command locally.

Machines are named by their id, a slug of their name such as mac-studio; the name works too. The app, the CLI and MCP servers can all run at once and see each other’s changes.

Machines

muxen status [--refresh]                     # overview and what needs attention
muxen machines
muxen machine beacon                         # everything about one machine
muxen check                                  # check every machine now and print a report
muxen ssh-hosts                              # your ssh config, your tailnet, this network
muxen add-machine --name Beacon --host you@beacon.local
muxen rename-machine beacon "Beacon server"  # the id stays the same
muxen remove-machine beacon                  # nothing on the machine changes
muxen disconnect beacon                      # stop connecting; its sessions go on there
muxen connect beacon
muxen connection beacon [--direct on|off]
muxen wake beacon                            # Wake on LAN
muxen power win-test off                     # a VM or a cloud machine

See Machines and Connections.

Agent sessions

muxen session ls
muxen session start beacon claude --cwd ~/code/api --prompt "Fix the failing test"
muxen session read beacon/claude-3f9a
muxen session question beacon/claude-3f9a  # what it's asking, and the options
muxen session answer beacon/claude-3f9a 1
muxen session send beacon/claude-3f9a "Also update the README"
muxen session attach beacon/claude-3f9a    # use it in this terminal
muxen session rename beacon/claude-3f9a "API tests"
muxen session restart beacon/claude-3f9a
muxen session stop beacon/claude-3f9a

Agents are claude, codex, opencode, gemini, amp, pi, or shell for a plain shell. See Agent sessions.

Workspaces

muxen ws create --platform linux --repo acme/api --ref main
muxen ws create --docker --image node:22 --repo acme/web  # in a fresh container
muxen ws ls
muxen ws exec ws-7f3a2c -- cargo test
muxen ws exec ws-7f3a2c --background -- npm run dev
muxen ws cat ws-7f3a2c .muxen/logs/1.log
echo 'hello' | muxen ws write ws-7f3a2c notes.txt
muxen ws files ws-7f3a2c src --depth 1
muxen ws changes ws-7f3a2c                                # git status and the diff
muxen ws sync ws-7f3a2c ~/code/api --push                 # or --pull; --delete mirrors deletions
muxen ws shell ws-7f3a2c                                  # a shell there, for you
muxen ws rm ws-7f3a2c [--keep-files]
muxen ws allow nas --off                                  # no workspaces on this machine

ws is short for workspace. Leave out the machine and Muxen picks the least-loaded one that matches --platform.

Files and editors

muxen files beacon:~/build                    # what's in a folder (alias: ls)
muxen cp beacon:~/build/app.tar.gz mac-studio:~/Downloads
muxen edit beacon:~/code/api [--editor zed] [--print]

edit opens the folder over ssh in Zed, Cursor or VS Code; --print shows the command instead. See Files.

Running things

muxen run --on beacon,mac-studio -- df -h /  # one command on several machines
muxen run --all -- uptime                    # every machine that's online
muxen ps beacon [-n 20]                      # busiest processes and GPUs
muxen kill beacon 4242 [--force]
muxen ports beacon                           # what's listening
muxen forward beacon 3000                    # its port 3000 at localhost:3000, until Ctrl-C

run exits 1 when any machine failed. See Run on machines and Servers.

Logs and services

muxen logs beacon --list  # what there is to read
muxen logs beacon         # the system log
muxen logs beacon --unit nginx -n 500 --grep error
muxen logs beacon --container postgres --follow
muxen logs beacon --file /var/log/syslog
muxen services beacon     # services and containers, failed first
muxen services beacon restart nginx
muxen services beacon stop postgres --container

See Logs and services.

Desktops

muxen desktop shot beacon [-o screen.jpg]
muxen desktop input beacon '[{"type":"click","x":640,"y":400},{"type":"text","text":"hello"}]'
muxen desktop displays beacon                   # its monitors, with their ids
muxen desktop add beacon --size 2560x1440 --name Side
muxen desktop set beacon <display> --size 3840x2160 --scale 2
muxen desktop remove beacon <display>

shot and input take --display for one monitor. Input coordinates are in the screenshot’s pixels. See Desktops.

VMs and schedules

muxen vm options
muxen vm create win-test --system windows-11 --on beacon
muxen vm create dev --system ubuntu-24.04 --install claude,codex
muxen vm destroy win-test

muxen schedule ls [--on beacon]
muxen schedule add beacon --name Tests --every day --at 09:00 --command "make test"
muxen schedule add beacon --name Triage --every weekdays --at 08:30 --agent claude --prompt "Triage new issues" --folder ~/code/api
muxen schedule run beacon <id>
muxen schedule log beacon <id>
muxen schedule rm beacon <id>

--every takes 15m, 2h, day, weekdays or days like mon,thu. See VMs and Schedules.

Cloud machines

muxen cloud login --browser      # or --token TOKEN, or --doctl
muxen cloud options              # regions, sizes, prices
muxen cloud create build-box --region nyc3 --size s-2vcpu-4gb
muxen cloud usage
muxen cloud power build-box off  # still billed while off
muxen cloud destroy build-box
muxen cloud logout

A cloud machine costs money every hour it exists. See Cloud machines.

GitHub, git and runners

muxen github inbox
muxen github repos
muxen github repo acme/api
muxen github issue acme/api#632
muxen github accounts
muxen github use work-login
muxen checkouts --repo acme/api
muxen git status beacon
muxen git setup beacon --identity --credentials

muxen watch acme                       # or acme/api; unwatch to stop
muxen runners [--machine beacon] [--state offline]
muxen jobs
muxen install beacon --count 2 [--label gpu] [--mode auto|service|background|docker]
muxen runner restart beacon/beacon-01  # start, stop, restart, logs, remove
muxen cancel-run 123456789

github is also gh. See GitHub and Runners.

Usage, settings and files

muxen usage [--days 30] [--machine beacon]    # tokens and cost at API prices
muxen settings                                # show them
muxen settings --poll 20 --check-interval 15  # GitHub every 20 s, machines every 15 min
muxen paths                                   # where Muxen keeps its files
muxen init                                    # write a starter config.toml
muxen mcp                                     # the MCP server, for agents

Muxen keeps its files in ~/.config/muxin (%APPDATA%\muxin on Windows). Set MUXIN_HOME, or pass --config-dir, to use another folder; a separate one is handy for trying things without touching your real setup.