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	claude
Model	(per-launch)	default, opus, sonnet, haiku, o3, o4-mini	default
Permissions	(per-launch)	default, bypass, plan, acceptEdits, dontAsk	default
Runtime	runtime	local, container, remote	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.

Remote Sandboxes

Setting Runtime: remote provisions an isolated OpenShell sandbox for the agent instead of running it locally. This requires the OpenShell gateway to be running first — see Remote Sandboxes for the full setup guide.

When you launch with runtime remote:

1. aimux provisions a sandbox via the OpenShell gateway
2. The agent starts inside the sandbox with model traffic routed through the gateway’s inference proxy — no API keys enter the sandbox
3. The session tab opens automatically so you can interact with the agent immediately
4. The sandbox name (e.g., ax-cl-33d0) and your selected directory are tracked so the dashboard shows the real project name

TUI: Use h/l on the Runtime row to select remote. Web: Select remote in the Runtime option group of the launch dialog.

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.