---
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/`.
