Skip to main content
Mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, mux run executes a single request to completion and exits.

​
mux run

Execute a one-off agent task: 
# Basic usage - run in current directory
mux run "Fix the failing tests"

# Specify a directory
mux run --dir /path/to/project "Add authentication"

# Use SSH runtime
mux run --runtime "ssh user@myserver" "Deploy changes"

# Pipe instructions via stdin
echo "Add logging to all API endpoints" | mux run

# JSON output for scripts
mux run --json "List all TypeScript files" | jq '.type'

​
Options

OptionShortDescriptionDefault
--dir <path>-dProject directoryCurrent directory
--model <model>-mModel to use (e.g., anthropic:claude-sonnet-4-5)Default model
--runtime <runtime>-rRuntime: local, worktree, or ssh <host>local
--mode <mode>Agent mode: plan or execexec
--thinking <level>-tThinking level: off, low, medium, highmedium
--timeout <duration>Timeout (e.g., 5m, 300s, 300000)No timeout
--jsonOutput NDJSON for programmatic useOff
--quiet-qOnly output final resultOff
--workspace-id <id>Explicit workspace IDAuto-generated
--config-root <path>Mux config directory~/.mux

​
Runtimes

  • local (default): Runs directly in the specified directory. Best for one-off tasks.
  • worktree: Creates an isolated git worktree under ~/.mux/src. Useful for parallel work.
  • ssh <host>: Runs on a remote machine via SSH. Example: --runtime "ssh user@myserver.com"

​
Output Modes

  • Default (TTY): Human-readable streaming with tool call formatting
  • --json: NDJSON streaming - each line is a JSON object with event data
  • --quiet: Suppresses streaming output, only shows final assistant response

​
Examples

# Quick fix in current directory
mux run "Fix the TypeScript errors"

# Use a specific model with extended thinking
mux run -m anthropic:claude-sonnet-4-5 -t high "Optimize database queries"

# Run on remote server
mux run -r "ssh dev@staging.example.com" -d /app "Update dependencies"

# Scripted usage with timeout
mux run --json --timeout 5m "Generate API documentation" > output.jsonl

​
mux server

Start the HTTP/WebSocket server for remote access (e.g., from mobile devices): 
mux server --port 3000 --host 0.0.0.0
Options:
  • --host <host> - Host to bind to (default: localhost)
  • --port <port> - Port to bind to (default: 3000)
  • --auth-token <token> - Optional bearer token for authentication
  • --add-project <path> - Add and open project at the specified path

​
mux desktop

Launch the desktop app. This is automatically invoked when running the packaged app or via electron .: 
mux desktop
Note: Requires Electron. When running mux with no arguments under Electron, the desktop app launches automatically.

​
mux --version

Print the version and git commit: 
mux --version
# v0.8.4 (abc123)