Launching Agents

The Launcher

The launcher (:new in TUI, + Launch in web dashboard, aimux spawn on CLI) configures a new agent session across six axes:

Axis	Config key	Values	Default
Provider	(per-launch)	claude, codex, gemini	claude
Model	(per-launch)	default, opus, sonnet, haiku, o3, o4-mini, gemini-2.5-pro	default
Permissions	(per-launch)	default, bypass, plan, acceptEdits, dontAsk	default
Runtime	runtime	local, container	local
Execution	execution	local, hybrid	local
Shell	shell	/bin/zsh, /bin/bash, /bin/sh	$SHELL
Session	session_manager	tmux, direct	tmux
Tracing	(per-launch)	ON, OFF	ON if OTEL receiver is running

TUI

Type :new to open the launcher overlay. Navigate with:

• j/k to move between fields
• h/l to cycle options within a field
• Space to toggle tracing
• Enter to launch
• Esc to cancel

Web Dashboard

Click + Launch in the header bar. The launch API accepts all axes:

{
  "provider": "claude",
  "dir": "/path/to/project",
  "model": "opus",
  "mode": "plan",
  "runtime": "local",
  "execution": "local",
  "shell": "/bin/zsh",
  "session_manager": "tmux",
  "otel_enabled": true
}

CLI

aimux spawn claude \
  --dir ~/projects/myapp \
  --model opus \
  --mode plan \
  --runtime local \
  --execution local \
  --shell /bin/zsh \
  --session tmux \
  --otel

Runtime vs Execution

These are the two most commonly confused axes:

• Runtime = WHERE the agent CLI binary runs (your laptop or a container)
• Execution = WHERE the agent’s tool calls run (locally or forwarded to a remote host)

              Agent process    Tool calls (edit, shell, test)
local:        laptop           laptop
container:    container        container
hybrid:       laptop           remote (K8s pod / SSH host)

Hybrid means the agent runs on your laptop but its Edit/Bash/Write calls are forwarded to a remote machine. The session is local; the work is remote.

Session Manager

• tmux (default): Sessions persist after detach. You can close aimux and reattach later. Sessions appear with tmux ls.
• direct: Agent runs in the foreground. When you close the terminal, the agent dies. Good for quick one-shot tasks.

Quick Launch Directories

Pre-configure directories for fast access:

quick_launch:
  directories:
    - "~/projects/my-app"
    - "~/projects/my-lib"

These appear at the top of the directory picker.

Task-Driven Launch

With Google Tasks integration enabled, launch agents with task context. See Tasks Integration for setup.