---
title: tmux
description: Default runtime on macOS and Linux. Each agent gets its own tmux window.
---

<div style={{ display: "flex", alignItems: "center", gap: "0.75rem", margin: "0.5rem 0 1.25rem" }}>
  <Logo name="tmux" size={28} />
  <span style={{ fontSize: "0.8125rem", color: "var(--color-fd-muted-foreground)" }}>Slot: <code>runtime</code> · Name: <code>tmux</code></span>
</div>

AO uses [tmux](https://github.com/tmux/tmux) as the default runtime on macOS and Linux. Each session lives in its own tmux window under a single AO-managed session, and you can attach to any of them interactively.

<PlatformSupport macos="full" linux="full" windows="none" note={<>Windows has no tmux. Use <a href="/docs/plugins/runtimes/process">process</a> instead.</>} />

## Install

macOS:

```bash
brew install tmux
```

Debian/Ubuntu:

```bash
sudo apt install tmux
```

Arch:

```bash
sudo pacman -S tmux
```

AO needs tmux 3.2 or newer.

## Use

```yaml title="agent-orchestrator.yaml"
runtime: tmux
```

No plugin-level config — this is the default on macOS/Linux so you can also omit the key entirely.

## How it works

- Every AO-managed process lives in a tmux window inside a per-project tmux session.
- Agents start via `tmux send-keys` so their output is captured.
- For long commands (>200 characters), AO writes a temp bash script and sources it, because `tmux send-keys` truncates paste buffers.

## Attaching

```bash
ao session attach <sessionId>
```

Or from inside tmux, switch windows manually. You can detach at any time (`Ctrl-b d`) and AO keeps running.

## Troubleshooting

- **`tmux server not running`.** `ao start` launches the server for you; if you killed it, run `ao start` again.
- **Window disappears after agent exits.** Intentional — AO cleans up finished windows. The session metadata is archived under `~/.agent-orchestrator/.../archive/`.
