How-to guides¶

One task each, for when you already know your way around the app and want to get something particular done.

Setting up¶

• Set up Agents on this Mac: install Agents Host, run your agents and the control plane here, and pair the window.
• Connect a window or phone: pair another Mac, an iPhone, an iPad or a browser, change what it may do, and forget it.
• Use Agents in a browser: open Agents in Safari or Chrome on the Mac that runs Agents Host, pair it once, and forget it.
• Add a server: make a Linux server, or another Mac, a host of your control plane.
• Start workspaces from Agents: let the control plane start and stop the machines your servers run on, and press Start on a stopped one.
• Add a workspace provider: a preset, your own commands, a tool map, or a provider of your own.
• Run the control plane in the cloud: on a machine you rent, at your own domain with a public certificate.
• Run the control plane as several copies: over one bucket, behind a load balancer, so it stays up when your Mac sleeps.
• Move an existing set-up across: bring the earlier app's agents, devices and servers to a control plane, once.
• Release Agents Host: publish the Developer ID download on GitHub by tagging main, and set up its signing secrets once.
• Fix Agents Host when it won't start: see why a login item isn't running, Repair it, and send diagnostics with a report.

Projects¶

• Chat without a project: start a chat with no folder to pick, and keep a file for a later chat.
• Add a project: add a folder or clone a Git URL, and archive a project you are done with.
• Start an agent in its own worktree: give an agent its own checkout and branch.
• Give an agent more folders and MCP servers: let one agent work across two repositories, or reach a server only it needs.

Agents¶

• Choose a runtime, model and mode: what an agent runs on, and the meter for its context and cost.
• Pick up a conversation started somewhere else: carry on in Agents with one you began in Terminal, or delete one.
• Answer a question or a permission request: from the Mac, the iPhone or iPad, or a notification.
• Send a prompt while an agent is working: let it wait its turn, or put it into the running turn with Send now.
• See what needs you from your Home screen: the number of sessions waiting on you, and a tap that opens one.
• Watch an agent's background work: the shells and subagents it runs in the background, their output, and Stop.
• Use a shell in an agent's folder: the Terminal pane, one shell to a tab.
• Attach files and pictures to a prompt: drag, paste, the paperclip, or an @ mention.
• Read an agent's changes: the Changes pane, edits in the conversation, and the files pane.
• Follow a live document: watch a document take shape as an agent writes it, and type on it yourself.
• Look at an HTML page an agent wrote: a report or wireframe as a page, with its stylesheet and pictures, and what it is not allowed to do.
• Stop and archive agents: what each does, and what each keeps.
• Sign a runtime in: sign Claude Code, Codex, Copilot, Cursor, Grok or Antigravity in or out from the app, and give Gemini its key.
• Assess a runtime: have an agent on a runtime work through the app's tools, and read the app's own score of it.
• Share skills, instructions and servers with every agent: put them in ~/.agents once, for every runtime and project.
• Add a skill from a catalogue: search skills.sh, look before it goes in, and add it for yourself or to a project.
• Choose marketplaces: which marketplaces Add server… and Add skill… search, and adding your own, such as your company's MCP registry.
• Add an MCP server from the registry: search GitHub's MCP registry or another, see what would run, and add it for yourself or to a project. Secrets stay in your own secrets.env.
• Add an MCP server by hand: a local command or a remote URL that is not on the registry, verified to answer before anything is written.
• Share one copy of a local MCP server: mark a server "hosted": true so the app runs it once per host for every agent and workflow.
• Sign in to an MCP server: a remote server that asks for OAuth, such as GitHub's, signed in to in your browser so agents start with it.
• Keep going when a runtime runs out: see which runtimes are out, and continue a chat's work in a new chat on another.
• Limit what agents spend: the Spending page, and a limit per agent or per day.

Servers¶

• Add a server: make a Linux server a host of your control plane.

Automation¶

• Set up a workflow: start agents on a schedule, or when another agent finishes, stops or asks.
• Start a workflow from an MCP event: an agent each time an MCP server reports something, such as a pull request's checks failing.
• Pin a page to a project: a document or an HTML page under its project in the sidebar, live as it changes.
• Hand files to a workflow: drop a file into a project's drop box and have a workflow work on it.
• Have an agent wait for something: checks passing, another agent finishing or the Mac waking, and agents telling each other.