---
title: Launching Agents
description: Six-axis agent launcher, quick launch directories, and task-driven launches.
---

## 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:

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

### CLI

```bash
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:

```yaml
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](/guides/tasks/) for setup.
