Getting started with MuxAgent in five minutes

Most developer tools lose people between “this sounds interesting” and “I have it running on my machine.” The gap is rarely technical. It is motivational. The install instructions are long, the prerequisites are vague, and the first useful moment is buried behind configuration that only matters later.

MuxAgent tries to compress that gap. The goal is a working setup — CLI installed, mobile app paired, first task running — in a single short session. Not because the product is shallow, but because nothing teaches a workflow tool faster than using it on a real task.

This guide walks through the full path from zero to a working MuxAgent setup. If you already have the CLI installed, skip ahead to pairing the mobile app.

What you are setting up

Before touching the terminal, it helps to know what the pieces are.

MuxAgent has two main surfaces:

1. The CLI runs on the machine where your code lives — your laptop, a workstation, a dev server. It provides the task system (graph-based workflows with planning, review, approval, implementation, and verification) and the daemon that makes remote control possible.

2. The mobile app connects to your machines and gives you a live view of running agent sessions. You can see what the agent is doing, review approval checkpoints, and intervene — all from your phone.

The two communicate through an end-to-end encrypted relay. The relay routes encrypted traffic but cannot read the content. Cryptographic keys are generated locally on your devices. That means the setup does not require an account on a central platform. Pairing is device-to-device, mediated by a QR code.

That is the whole architecture for getting started. One CLI, one app, one encrypted channel between them. From that same foundation you get mobile control and multi-machine support.

Step 1: Install the CLI

On macOS or Linux, run the install script:

curl -fsSL https://raw.githubusercontent.com/LaLanMo/muxagent-cli/main/install.sh | sh

The script downloads the right binary for your platform and puts it in /usr/local/bin if writable, otherwise ~/.local/bin. If you prefer to inspect the script before running it, the source is on GitHub.

On Windows, download the latest muxagent-windows-*.zip from the releases page and add the binary to your PATH.

Verify the install:

muxagent version

If you see a version number, the CLI is ready.

Step 2: Start the daemon and pair the mobile app

Run:

muxagent daemon start

On first run, this triggers the setup flow. The CLI generates local cryptographic keys, registers with the relay, and displays a QR code in your terminal.

Now open the MuxAgent mobile app. You can get it from Google Play. (iOS is coming soon.)

In the app, scan the QR code from your terminal. The app and the CLI perform a key exchange, establish the encrypted channel, and complete pairing.

Once the QR code is scanned and approved, the daemon starts automatically. Your phone is now the remote control for agent sessions on this machine.

Quick status check

After pairing, confirm everything is healthy:

muxagent auth status
muxagent daemon status

If both commands report a connected state, you are ready to run your first task.

Common setup issues

The QR code does not appear. Make sure your terminal supports inline graphics or that the fallback text QR is visible. Try making the terminal window wider.

The daemon does not start after pairing. Check that no other process is using the same port. Run muxagent daemon status to see what state it is in.

The CLI is not found after install. If the script fell back to ~/.local/bin, make sure that directory is on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile if needed.

For a comprehensive list of solutions to connection, pairing, and session problems, see the troubleshooting guide.

Step 3: Run your first task

With the daemon running, launch the interactive task CLI:

muxagent

This opens the workflow TUI. It will ask you to:

1. Pick a workflow config. For your first task, choose default. This runs the full graph: plan, review, approve, implement, verify. It is the safest starting point because it lets you see every stage explicitly.

2. Describe the task. Give a concrete, bounded task. Something like:

   • “Add a health-check endpoint to the API server that returns 200 OK.”
   • “Fix the off-by-one error in the pagination logic in src/api/list.go.”
   • “Write a unit test for the parseConfig function in lib/config.ts.”

   Avoid vague instructions like “clean up the code” or “make it better.” Agents finish more reliably when the outcome is specific. (For more on writing effective task briefs, see how to structure AI coding tasks that agents can finish.)

3. Choose a runtime. MuxAgent supports Codex and Claude Code. Pick whichever you already use, or try both on separate tasks to compare.

Once you submit, the workflow begins.

What happens during the workflow

With the default config, the agent moves through five stages:

Plan. The agent reads the codebase, identifies the relevant files, and drafts a plan for the change. You can see this happening in the TUI.

Review. The system evaluates the plan for quality. If the plan is weak, it loops back to planning. If it passes, the workflow advances.

Approve. This is where you step in. The workflow pauses and waits for your approval. You can approve from the terminal or from the mobile app. Read the plan, check that the approach is sound, and approve or reject.

This is the moment that earns the default config its name — it puts a human checkpoint before any code is changed. If you want to understand why that checkpoint is valuable rather than just annoying, see why approval checkpoints are a feature, not a slowdown.

Implement. Once approved, the agent edits the code. It follows the plan it already outlined and you already approved.

Verify. The agent runs the checks specified in the task. If verification fails, the workflow loops back to implementation for another attempt. If it passes, the task is done.

What recovery looks like

Recovery is where structured workflows pay for themselves. If verification fails — say the tests do not pass or the build breaks — the workflow does not just stop and tell you it failed. It sends the task back to implementation for another attempt, using the failure information as context.

If the failure is really a planning problem — the approach was wrong, not just the execution — review can send the task back to planning entirely. That means the system handles both small fixes and larger course corrections without requiring you to start over from scratch.

You do not need to learn these mechanics upfront. Just run a task and watch what happens when a step does not go perfectly. The recovery paths are visible in the workflow itself.

Approving from your phone

If you step away from the terminal while the agent is working, the mobile app will show you the running session. When the workflow reaches the approval stage, you can review and approve right from your phone.

That is the remote-control experience in its simplest form. The agent keeps working on your machine. You stay reachable wherever you are.

Step 4: Try a different workflow config

Once you have seen the full default flow, try a different config to see how the graph changes.

plan-only stops after review. No code is changed. This is useful when the task is still fuzzy and you want a reviewed plan before committing to implementation.

autonomous removes the approval step. The agent moves from review directly to implementation. This is faster and works well for low-risk, well-scoped tasks.

yolo runs fully autonomously in multi-wave mode. It adds an evaluation step after verification so the system can plan the next wave of work. This is for larger tasks that are too big for a single pass but can be decomposed into bounded increments.

Each config is a different workflow graph with different checkpoints, recovery paths, and levels of human involvement. The right choice depends on the task’s risk, ambiguity, and how much you want to stay in the loop. (For a detailed guide on when to use each, see how to choose the right MuxAgent workflow config.)

Step 5: Add a second machine (optional)

Once the first machine is working, you may want to add a workstation or dev server. The process is the same enrollment flow you already did.

On the new machine:

curl -fsSL https://raw.githubusercontent.com/LaLanMo/muxagent-cli/main/install.sh | sh
muxagent daemon start

Scan the new QR code in the same mobile app. Both machines are now reachable from one phone.

This matters when agent work spreads beyond the laptop — heavier builds on a workstation, long-running tasks on a dev server, or inspection on a production-adjacent box. The mobile app shows sessions from all paired machines in one place.

Customizing workflow configs

The built-in configs cover the most common patterns, but they are not locked down.

Workflow configs live as task config bundles under ~/.muxagent/taskconfigs. You can clone any built-in config and modify the YAML to change:

• the workflow graph (which stages exist and how they connect),
• the prompts used at each stage,
• the runtime (Codex or Claude Code),
• iteration limits,
• and whether clarification is enabled.

Start with the built-ins until you know where your actual friction is. Then customize with evidence.

What to do next

You now have a working MuxAgent setup: CLI installed, mobile app paired, and a first task completed through a structured workflow.

Here are the most useful next moves depending on what matters to you:

If you want better task results, focus on how you write task briefs. A strong brief with clear outcomes, bounded scope, and explicit verification criteria will dramatically improve what the agent produces.

If you want to understand the security model, the relay is zero-knowledge, keys are local, and the CLI is open source. You can inspect the implementation and self-host the relay if your environment requires it. See why trust boundaries matter for remote AI agent control for the full picture.

If you want to add more machines, just repeat the install-and-pair flow on each one. The mobile app scales to as many paired machines as you need.

If you want to go deeper on workflow design, the blog covers graph-based workflows, approval economics, task structuring, and runtime portability in detail. Start with whichever topic matches your current question.

The best way to learn MuxAgent is to keep using it on real tasks. The workflow will teach you which config fits which job, which tasks need tighter briefs, and when remote control stops being a convenience and starts being the thing that keeps your day moving.