156 lines
5.2 KiB
Plaintext
156 lines
5.2 KiB
Plaintext
---
|
|
title: Platforms
|
|
description: Choose the right AO runtime, terminal, and notification setup for macOS, Linux, Windows, and remote hosts.
|
|
---
|
|
|
|
import { Callout } from "fumadocs-ui/components/callout";
|
|
|
|
AO's core workflow is the same on every platform: create an isolated workspace, run an agent, track the PR, react to CI and review events, and show progress in the dashboard.
|
|
|
|
The platform differences come from the tools used to run and attach to long-lived sessions.
|
|
|
|
<PlatformSupport
|
|
macos="full"
|
|
linux="full"
|
|
windows="partial"
|
|
note={<>Windows support is actively improving. Use the process runtime instead of tmux.</>}
|
|
/>
|
|
|
|
## Recommended Setup
|
|
|
|
| Platform | Runtime | Notifications | Notes |
|
|
| --- | --- | --- | --- |
|
|
| macOS | `tmux` | `desktop`, Slack, Discord, webhook | Best local experience. iTerm2 attach support is macOS-only. |
|
|
| Linux | `tmux` | `desktop`, Slack, Discord, webhook | Best server and workstation setup. Desktop notifications need `notify-send`. |
|
|
| Windows | `process` | Slack, Discord, webhook | Native tmux and iTerm2 are unavailable. Windows support is in progress. |
|
|
| Container or remote VM | `process` or `tmux` | Slack, Discord, webhook | Use persistent storage for AO data and protect the dashboard with your own auth. |
|
|
|
|
## macOS
|
|
|
|
macOS is the default local development target.
|
|
|
|
Install tmux before using the default runtime:
|
|
|
|
```bash
|
|
brew install tmux
|
|
```
|
|
|
|
Recommended config:
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
defaults:
|
|
runtime: tmux
|
|
notifiers:
|
|
- desktop
|
|
```
|
|
|
|
What works well on macOS:
|
|
|
|
| Capability | Status |
|
|
| --- | --- |
|
|
| tmux-backed worker sessions | Supported |
|
|
| Browser dashboard terminal | Supported |
|
|
| iTerm2 attach/open helpers | Supported |
|
|
| Desktop notifications | Supported |
|
|
| macOS idle sleep prevention while AO runs | Supported |
|
|
|
|
<Callout type="info" title="Lid-close sleep still wins">
|
|
AO can prevent idle sleep on macOS while agents run, but it cannot override hardware lid-close sleep. Use normal clamshell mode if you need the machine available while closed.
|
|
</Callout>
|
|
|
|
## Linux
|
|
|
|
Linux is a good fit for local workstations, remote development machines, and always-on hosts.
|
|
|
|
Install tmux with your distribution package manager:
|
|
|
|
```bash
|
|
sudo apt install tmux
|
|
```
|
|
|
|
Recommended config:
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
defaults:
|
|
runtime: tmux
|
|
notifiers:
|
|
- desktop
|
|
```
|
|
|
|
What to know:
|
|
|
|
| Capability | Status |
|
|
| --- | --- |
|
|
| tmux-backed worker sessions | Supported |
|
|
| Browser dashboard terminal | Supported |
|
|
| iTerm2 attach/open helpers | Not available |
|
|
| Desktop notifications | Supported when `notify-send` is installed |
|
|
| Remote dashboard access | Supported through port forwarding, Tailscale, or your proxy |
|
|
|
|
If you are running AO on a headless Linux host, prefer Slack, Discord, or webhook notifications over desktop notifications.
|
|
|
|
## Windows
|
|
|
|
<Callout type="warn" title="Windows support is in progress">
|
|
The native Windows path uses `runtime: process`. The core spawn and PR workflow is available, but tmux-specific workflows and iTerm2 helpers do not apply.
|
|
</Callout>
|
|
|
|
Recommended config:
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
defaults:
|
|
runtime: process
|
|
notifiers:
|
|
- slack
|
|
```
|
|
|
|
What works:
|
|
|
|
| Capability | Status |
|
|
| --- | --- |
|
|
| `ao start`, `ao stop`, `ao dashboard` | Supported |
|
|
| `ao spawn` and `ao spawn --prompt` | Supported through the process runtime |
|
|
| GitHub, GitLab, and Linear tracker/SCM integrations | Supported when their CLIs or credentials are configured |
|
|
| Browser dashboard terminal | Supported through the direct PTY server |
|
|
| Slack, Discord, webhook, Composio, and OpenClaw notifiers | Supported |
|
|
|
|
What is limited:
|
|
|
|
| Capability | Status | Use instead |
|
|
| --- | --- | --- |
|
|
| `runtime: tmux` | Not available natively | `runtime: process` |
|
|
| iTerm2 terminal integration | Not available | Browser dashboard terminal |
|
|
| Desktop notifier | No-op on Windows | Slack, Discord, webhook, Composio, or OpenClaw |
|
|
| tmux attach commands | Not available | Dashboard terminal and AO session commands |
|
|
|
|
Use PowerShell or Git Bash for normal CLI commands. If a command behaves differently because of shell quoting, put longer instructions in a file and send them with `ao send --file`.
|
|
|
|
## Containers And Remote Hosts
|
|
|
|
AO can run on a remote machine or inside a container, but the dashboard has no built-in authentication. Put it behind your own access layer before exposing it beyond localhost.
|
|
|
|
Recommended config for containers:
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
defaults:
|
|
runtime: process
|
|
notifiers:
|
|
- webhook
|
|
```
|
|
|
|
Operational notes:
|
|
|
|
- Mount or preserve AO's data directory so session metadata survives restarts.
|
|
- Forward the dashboard port, usually `3000`, only to trusted networks.
|
|
- Prefer network notifiers over desktop notifications.
|
|
- Use `tmux` only if it is installed and you want attachable terminal sessions inside the host.
|
|
|
|
## Choosing A Runtime
|
|
|
|
| Runtime | Best for | Tradeoff |
|
|
| --- | --- | --- |
|
|
| `tmux` | macOS/Linux machines where you want durable, attachable terminal sessions | Requires tmux and does not work natively on Windows |
|
|
| `process` | Windows, containers, and simpler process-managed environments | Less of the workflow is tmux-attachable |
|
|
|
|
Start with the recommended runtime for your OS. Change it only when the default runtime does not match where AO is running.
|