# Alto

> Alto is the backplane for people and agents. Your terminals keep running, on every machine you have, and tell you when one needs you. Plug in from any terminal, Alto's app or your phone, and your agents plug in too. Tailscale secure access built in.

Alto is the backplane for people and agents: the layer that work in terminals runs through.
Every session is alive (it outlives the window, updates and crashes), addressable (machine:id,
from any machine), legible (it says what it is doing and when it needs a person) and open (to
any terminal, Alto's own app, a phone or an agent). It works underneath the tools people already
use (their terminal, ssh, agent apps and managers); under the hood it is a terminal multiplexer. Sessions run on every server in a company or homelab (setup with one command, trust by
Tailscale tag, one queue of what needs a person across devices), with secure remote access from
anywhere through Tailscale, which is built in (nothing listens on the LAN or internet; devices
prove their identity).

Alto is a small service on each machine and one command, alto, for macOS, Linux and Windows,
written in Rust. Its own app is optional: a terminal emulator built on libghostty, with GPUI
for the window. Every session is its own background process, kept by a small service, so
programs (Claude Code, Codex, builds, dev servers) keep running when the window closes, the app
updates or crashes. Sessions save their screen as they go and come back after a reboot with a
Run again button that resumes agent conversations. Each tab shows an agent state: working, needs
you, done or idle, from terminal signals and from hooks for Claude Code and Codex. Other
computers reach sessions over Tailscale only. A work pane lets an agent run commands in a
terminal the person can see, with `alto run` returning only the output and exit status.

Status: early. Built: the terminal, persistent sessions, reboot recovery, agent status,
remote devices, work panes, MCP, the fleet view, placement, phone apps (iPhone in TestFlight,
Android). Planned: agents coordinating agents (Phase 7), automatic updates and packages
(Phase 8), fleet groups, rules, single sign-on and audit log (Phase 9). A Homebrew formula is coming soon;
until then it is built from source.

## Docs
- Docs home: https://www.altohq.io/docs/
- Install: https://www.altohq.io/docs/start/install/
- Working beside an agent: https://www.altohq.io/docs/agents/work-pane/
- MCP server: https://www.altohq.io/docs/agents/mcp/
- Remote access with Tailscale: https://www.altohq.io/docs/devices/remote-access/
- Running a fleet: https://www.altohq.io/docs/devices/fleet/
- Servers and containers: https://www.altohq.io/docs/devices/servers/
- CLI reference: https://www.altohq.io/docs/reference/cli/
- MCP tool reference: https://www.altohq.io/docs/reference/mcp/
- Comparison with other approaches: https://www.altohq.io/why/

## CLI commands (alto 0.0.1)
- alto open: Open a session in a Alto window, in a new tab if one is open, in this folder or DIR. Runs your login shell unless a program is given after `--`. (Plain `alto` starts one in the terminal it's typed in.) [aliases: term, terminal]
- alto new: Start a session and print its id. Runs your login shell unless a program is given after `--`
- alto fetch: Bring the branch of a session started with `new --repo` into this repository, as `alto/<device>-<id>`, its commits and all
- alto ls: List running sessions, and what each is doing [alias: list]
- alto reload: Move the service and running sessions onto the build installed now, after an update (nothing is downloaded). Sessions move in place, their programs still running: idle ones at once, working ones once idle. Those that can't (on Windows, ones started before they could) are listed as needing a restart, which --restart does
- alto report: Say what a session's program is doing (for an agent, or its hooks): idle, working, needs-you or done. A program may also say what it is (--kind) and values of its own (--set), which `describe` and `ls --json` show until it ends. With nothing to say, show it. Without --session, the session this runs in
- alto status: This device at a glance: the service and its start at login, Tailscale and remote access, devices, sessions, keep-awake, drain and the agents found here, with the command that fixes anything wrong. Asks this device only (`alto devices` asks the others)
- alto agents: Set up agents to report their state to Alto: Claude Code, Codex. Connect agents to Alto: their hooks (Claude Code, Codex: state, and which session a conversation is in), a skill pointing them at `alto guide` (Claude Code, Codex, OpenCode, Pi), and the MCP server (Claude Code). Leave out the command to see how each agent stands
- alto attach: Show a session in this terminal. Ctrl-\ detaches
- alto send: Type text into a session, then keys by name. With no --session, the work pane linked to this session (`alto work`)
- alto run: Run a command in a session's shell, where it shows, and print only its output, leaving with its exit status
- alto wait: Wait until a session's program reaches a state, or shows some text. Exits 0 then (printing what it found), 124 after --timeout, 125 if the session ends. With no id, the work pane linked to this session
- alto capture: Print a session's screen and scrollback as plain text (an ended session's, as it last saved them). With no id, the work pane linked to this session
- alto describe: What a session is and what it can be asked to do: its kind (agent, shell or job), its state, and its methods, each with what it takes and gives. With no id, the work pane linked to this session
- alto call: Ask a session to do one thing, by a method `describe` lists, with its arguments as JSON (`--args '{"last":20}'`, or `--args -` to read them from standard input). Prints what it gives back; the arguments are checked first, so a call refused changes nothing. Exits 2 when there's no such method or the arguments are wrong, 124 when it timed out, 125 when it couldn't, and `run`'s with the command's status
- alto reply: Reply to a message an agent was sent (12.10), from inside the session it was sent to: TEXT, or JSON with --json when the message asked for a reply of a certain shape. The sender gets it as data
- alto offer: Offer a method of this program's to its session, served by HANDLER: each call's arguments (JSON) on its standard input, its reply (JSON) on its standard output. Runs in a session, and stays running to serve calls until the process that started it ends (or with --keep, the session does). `alto describe` lists it; `alto call` calls it
- alto answer: Answer what a session's agent is asking (a permission prompt, a question) without its screen: `allow` or `deny`, or one of a question's options, as `describe` lists them. Refused when it's asking something else by now, so an answer never lands on another question
- alto guide: How to use Alto, for an agent running in it: its session, reaching other sessions and machines, waiting, and the rules. The hook for Claude Code points a new conversation here
- alto events: What happens, as it happens: sessions starting, ending, needing you and done; devices connecting, pairing, forgetting, blocking. A line each, or --json, until stopped. This device's, --on another's, or --all of them
- alto kill: End a session's program, or forget an ended session. --all ends every session here, asking first
- alto reset: Start over: end every session here (asking first), restart the service on the build installed now, and have open windows drop their tabs for one new one. `reload` is the one that keeps programs running
- alto pause: Stop agents typing into a session (`run`, `send` from an agent are refused there) until `alto resume`. You can still type. With no id, the work pane linked to this session
- alto resume: Let agents type into a session again
- alto work: The work panes linked to this session: where an agent running in it runs its commands (`alto run -- COMMAND`), beside it where you see them, here or on another device (`--on`). With nothing after it, lists them
- alto workspace: Named sets of sessions, on any machines, that open whole; kept by this device. A workspace holds sessions' addresses: forgetting it, or removing one, ends nothing. With nothing after it, lists them
- alto mcp: Serve the session commands to an agent over MCP, on standard input and output: `claude mcp add alto -- alto mcp`. Its tools run commands in your work pane (or a session it's told to use), as `alto run` does
- alto service: The background process that keeps sessions (started for you by any command): whether it's running and starts at login; start, stop or run it here; `install` to start it at login without the app
- alto settings: Show this device's settings, or one, or set one:
- alto fonts: Fonts Alto can download: list them, or install one
- alto pair: Pair with another person's device (your own, on the same Tailscale account, need no pairing). With nothing after it, shows a pairing string to type on the other device; with that string, pairs
- alto devices: Your other devices: those you reach (`--on NAME`), and those that reach this one. Forget, block or let one back in
- alto log: What happened on this device, and who did it: sessions started and ended, who attached, typed (how much, never what) and was refused, pairings. Each entry is signed by this device and names the one before, so `alto log verify` finds any changed, removed or moved
- alto access: Who may do what here: the rules (built in, and access.toml beside settings.toml)
- alto fleet: Sessions on every device you reach, and how many are working, need you or are done
- alto add: Make a machine ssh reaches one of yours: sends it the build for its OS and architecture, runs `alto install` there trusting your Tailscale login, waits for it to answer, and lists it. It needs Tailscale; without it, says how to install it and changes nothing
- alto install: Set Alto up on this device. At a terminal with no flags, it asks each step: Tailscale, starting at login, remote access, whom to trust, and the agents found here (their hooks, Claude Code's MCP server). With flags, -y or no terminal (a server, an image, cloud-init), it asks nothing: turns remote access on, trusts what `--trust` names, starts the service at login (on Linux, running with nobody logged in), and says how others reach it. Safe to run again
- alto uninstall: Take Alto off this device: end every session (asking first), stop the service and its start at login, take the agents' hooks out, and remove its state (devices, pairings, saved screens) and settings. The `alto` program itself stays; it says where

## MCP tools (alto mcp)
- run: Run a shell command in a terminal the person can see (their work pane, by default), typed at its prompt, and get back only the command's output and exit status as JSON: {output, exit, truncated, took, timed_out}. Refused, saying why, if something else is running there or someone has typed at the prompt.
- wait: Wait until the terminal's program reaches a state (idle, working, needs-you, done; or prompt: the shell back at its prompt), or prints text matching a regular expression. Default: until the prompt.
- read_screen: What the terminal shows now, as text, with where the cursor is: for full-screen programs (an editor, less, top). With `last`, the last lines of its scrollback instead.
- send_keys: Type into the terminal: text, then keys by name (Enter, Escape, Tab, Up, PageDown, F5, q; with C-, M- or S- before it: C-c, M-x, S-Tab). For answering a program; for shell commands, use run.
- describe: What a session is and what it can be asked to do, as JSON: its kind (agent, shell or job), its state (and what it's asking, if anything), and its methods, each with what it takes and gives (JSON Schema). Beyond the built-in ones (send, capture, wait, run, pause, resume, kill), a program in the session may offer its own, and an agent asking a question offers `answer`.
- call: Ask a session to do one thing, by a method `describe` lists, with its arguments as an object. Gives back {"ok": …} or {"error": {"code", "message"}}; the arguments are checked first, so a refused call changes nothing.
- work: The work panes linked to this conversation: terminals beside it, here or on other devices, where the other tools act by default.
- list_sessions: The sessions on this device, or on another (`device`), with what each is doing.
- use: Act on this session (on `device`, if given) from now on in this conversation, instead of the work pane; or start one there with new: true, or with new: true and `in`, on the least busy device that fits. With nothing, back to the work pane.

## Links
- Source: https://github.com/sanford/alto