Skip to main content
The CLI is designed for automation and scripting (CI/CD pipelines, batch processing, programmatic control). For interactive terminal experiences, consider tools like Claude Code or similar TUIs.
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.

GitHub Actions Guide

Learn how to use mux run in CI/CD pipelines

​
Installation

The CLI is available via npm and can be run directly with npx: 
# Run without installing
npx mux run "Fix the failing tests"

# Or install globally
npm install -g mux
mux run "Fix the failing tests"
Using npx mux is especially convenient for CI/CD pipelines where you don’t want to manage a global installation.

​
mux run

Execute a one-off agent task: 
# Basic usage - run in current directory
npx 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, ssh <host>, or docker <image>local
--mode <mode>Agent mode: plan or execexec
--thinking <level>-tThinking level: OFF, LOW, MED, HIGH, MAX, or 0–9 (model-relative, see Models)MED
--budget <usd>-bStop when session cost exceeds budget (USD)No limit
--experiment <id>-eEnable experiment (repeatable)None
--jsonOutput NDJSON for programmatic useOff
--quiet-qOnly output final resultOff

​
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"
  • docker <image>: Runs in a Docker container. Example: --runtime "docker node:20"

​
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 JSON output
mux run --json "Generate API documentation" > output.jsonl

# Limit spending to $2.00
mux run --budget 2.00 "Refactor the authentication module"

​
mux server

Start the HTTP/WebSocket server for remote access (for example, from a phone or another machine): 
mux server --host 0.0.0.0 --port 3000
Options:
  • --host <host> - Host/interface to bind to (default: localhost)
  • --port <port> - Port to bind to (default: 3000)
  • --auth-token <token> - Bearer token for HTTP/WS auth
  • --no-auth - Disable authentication entirely
  • --print-auth-token - Always print the auth token on startup
  • --allow-http-origin - Accept HTTPS browser origins when a TLS-terminating proxy forwards X-Forwarded-Proto=http
  • --ssh-host <host> - SSH hostname/alias used for editor deep links in browser mode
  • --add-project <path> - Add and open project at the specified path
Use --allow-http-origin only when HTTPS is terminated by an upstream reverse proxy and mux receives rewritten X-Forwarded-Proto=http headers. This compatibility mode is disabled by default. For non-CLI server starts (for example desktop/browser mode), set MUX_SERVER_ALLOW_HTTP_ORIGIN=1 to opt in. Auth token precedence:
  1. --no-auth
  2. --auth-token
  3. MUX_SERVER_AUTH_TOKEN
  4. Auto-generated token
GitHub owner login for browser sessions is configured separately via MUX_SERVER_AUTH_GITHUB_OWNER or serverAuthGithubOwner in ~/.mux/config.json. See Server Access.

​
mux acp

Start the ACP (Agent-Client Protocol) stdio bridge used by editor integrations: 
mux acp
Options:
  • --server-url <url> - URL of a running mux server
  • --auth-token <token> - Optional bearer token for authenticated server connections
  • --log-file <path> - Write ACP logs to a file instead of console stderr (helpful when your editor hides subprocess logs)
Environment variable equivalents:
  • MUX_SERVER_URL - Same as --server-url
  • MUX_SERVER_AUTH_TOKEN - Same as --auth-token
Use MUX_SERVER_AUTH_TOKEN for ACP auth; MUX_AUTH_TOKEN is not read by mux acp.

​
Set up Zed

Add a custom agent server in Zed that runs the ACP subcommand. If mux is installed globally: 
{
  "agent_servers": {
    "Mux": {
      "type": "custom",
      "command": "mux",
      "args": ["acp"]
    }
  }
}
If you prefer an ephemeral install: 
{
  "agent_servers": {
    "Mux": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "mux", "acp"]
    }
  }
}

​
Connect Zed to a remote mux server

You can point ACP at a remote mux server either with flags or environment variables. Using flags: 
{
  "agent_servers": {
    "Mux": {
      "type": "custom",
      "command": "mux",
      "args": ["acp", "--server-url", "https://mux.example.com", "--auth-token", "<token>"]
    }
  }
}
Using environment variables (for any mux acp process): 
MUX_SERVER_URL=https://mux.example.com \
MUX_SERVER_AUTH_TOKEN=<token> \
mux acp

​
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)

​
Debug Environment Variables

These environment variables help diagnose issues with LLM requests and responses.
VariablePurpose
MUX_DEBUG_LLM_REQUESTSet to 1 to log the complete LLM request (system prompt, messages, tools, provider options) as formatted JSON to the debug logs. Useful for diagnosing prompt issues.
Example usage: 
MUX_DEBUG_LLM_REQUEST=1 mux run "Hello world"
The output includes:
  • systemMessage: The full system prompt sent to the model
  • messages: All conversation messages in the request
  • tools: Tool definitions with descriptions and input schemas
  • providerOptions: Provider-specific options (thinking level, etc.)
  • mode, thinkingLevel, maxOutputTokens, toolPolicy