# Andon Docs > How to install Andon, add machines, work the board and run it for a team. ## Start here - [Andon docs](https://andon-docs.pages.dev/index.md): Find the section for what you’re doing, then the page. Each page is written for one reader. ## Use the board - [The board](https://andon-docs.pages.dev/guide/board.md): The board shows every card your teams are working on, in columns from idea to done. Moving a card between columns is how you tell Andon what to do with it: a card moved into Working starts running on a machine. - [The card](https://andon-docs.pages.dev/guide/card.md): Open a card to read what its run did, answer it, change its details or start it again. Everything about one piece of work is on the card: its notes, its run, its pull request, its comments and its history. - [Keyboard shortcuts](https://andon-docs.pages.dev/guide/shortcuts.md): Andon is built to steer many agents without the mouse. Press ? on the board to see this list in the app. - [Start work](https://andon-docs.pages.dev/guide/start-work.md): Start work turns one sentence into work on the board: a card, an import from Linear or Jira, a plan of several cards, or a study. Type or say what you want done, check what Andon understood, and press Enter. - [Plan a feature in the chat](https://andon-docs.pages.dev/guide/plan-in-chat.md): You can plan a feature in the chat (⌘J), with the in-app assistant or a machine’s Claude Code, Codex or Gemini CLI. You don’t need an Orca session or the andon CLI for it. The chat turns the feature into cards on the board and suggests which ones should ship together in one pull request. - [Needs you](https://andon-docs.pages.dev/guide/needs-you.md): Needs you is the list of everything waiting for a person: a question from a run, a finished turn, outputs to approve, a failure, a pull request that needs a hand. Work through it and the agents keep going. The count beside Needs you in the sidebar is how many items wait for you. - [Autopilot and how much Andon does](https://andon-docs.pages.dev/guide/autopilot.md): Andon can build, review and merge a team’s work on its own, or only do what you start. How much Andon does sets that for the workspace and for each team. Autopilot is the part that starts work: with it on, every card you move into a team’s Ready builds by itself. - [Teams, projects and PR groups](https://andon-docs.pages.dev/guide/teams-projects-and-pr-groups.md): Andon files work at four levels. A team is a repository, the settings for how its cards run, and the list of who sees it. A project is a goal inside a team, with a lead and dates. A PR group is the cards that ship together in one pull request. A card is one piece of work. - [Pull requests: review and merge](https://andon-docs.pages.dev/guide/review-and-merge.md): When a run finishes code work, it opens a pull request. Andon then reviews it, fixes what the review finds, waits for CI, and merges it, as far as the team’s level allows. This page says what happens on the way, and where you step in. - [Previews and annotations](https://andon-docs.pages.dev/guide/previews-and-annotate.md): A run can share the app it is building, running on its machine, as a preview link on its card. Open it to try the change before you merge it. Then Annotate a frame of it: drop pins and boxes where something should change, and send them to the agent as one reply. - [Where each setting is](https://andon-docs.pages.dev/guide/settings-map.md): Use this page when you know what you want to change but not where Andon keeps it. Settings has six pages. Some settings sit on pages that aren’t in the menu: you reach those by searching Settings, or by their address. - [Views, the filter bar and swimlanes](https://andon-docs.pages.dev/guide/views.md): The filter bar narrows the board to the cards you want, and a view saves that filter with a layout so you can come back to it: “My cards this cycle”, “Blocked”, “Needs review”. Saved views are listed in the sidebar under Views. Swimlanes split the board into a row per team or per project. - [Planning: estimates, cycles and milestones](https://andon-docs.pages.dev/guide/planning.md): Andon plans in two ways. A cycle is a team’s planning period, one to a few weeks long: you put cards in it, watch the burn line and carry over what didn’t get done. A milestone is a dated checkpoint in a project, such as “Private beta, Dec 1”, and its progress comes from the cards on it. Estimates size the cards so both can add up work instead of counting cards. - [Stats](https://andon-docs.pages.dev/guide/stats.md): Stats shows what one person got done on one day: cards finished, pull requests, runs and agent time. It also shows XP, a level, a daily quest and a streak, counted over the person’s whole history. Use it to look back on a day, or to see how a cycle went. - [Custom fields](https://andon-docs.pages.dev/guide/fields.md): A team can give its cards fields of its own, next to the built-in ones: Area, Customer, Severity, Spec link. Fields belong to a team, and its sub-teams’ cards have them too. Use them to sort and filter the board, and to hand a run extra facts about a card. - [Sub-tasks and relations](https://andon-docs.pages.dev/guide/subtasks-and-relations.md): Break a card into smaller cards with sub-tasks, and link cards that depend on each other with relations. A sub-task is a full card with its own key, column, recipe, owner and runs. A relation says one card blocks another, duplicates it, or is related to it, and a blocked card waits for its blocker before it runs. - [Workstreams](https://andon-docs.pages.dev/guide/workstreams.md): A workstream is a card whose work is split into steps that run one after another, or side by side, on their own. Each step is a card of its own with its own runs. Use one for work too big for one run, such as “migrate the billing service”: Claude proposes the steps, you approve them, and each step starts once the steps it waits for are done. - [Card templates and bulk edit](https://andon-docs.pages.dev/guide/templates-and-bulk-edit.md): A template is a card that makes cards: a Bug with its repro steps, a Release with its checklist. Bulk edit changes all the cards you pick in one go, with one Undo. - [Comments](https://andon-docs.pages.dev/guide/comments.md): Comments are for people to talk to each other on a card. The thread is separate from the chat with Andon (⌘J) and from a run’s conversation on the Run tab. Use it to ask a teammate, record a decision, or hand a remark to the card’s run. - [Activity, following and the archive](https://andon-docs.pages.dev/guide/activity.md): Needs you is for a run that needs you. Activity is for what happened: people’s changes and comments on the cards you follow. The Archive keeps cards that have left the board, and each card keeps a history of its changes. - [Card notes](https://andon-docs.pages.dev/guide/notes.md): A card’s notes are Markdown, and they stay Markdown: a run’s prompt gets exactly what people wrote. The editor helps you write it without adding syntax of its own. Comments use the same editor. - [The Dashboard, the phone and car mode](https://andon-docs.pages.dev/guide/dashboard-and-phone.md): Andon has three ways to keep up with the board when you aren’t at your desk. The Dashboard is a screen to leave open on an iPad or a spare monitor: it answers “does anything need me?” from across the room. The phone layout puts Needs you, the board, Start work, the chat and Activity under five tabs. Car mode reads out what needs you while you drive and takes your answers by voice. Settings → You holds the options for all three. - [Memory](https://andon-docs.pages.dev/guide/memory.md): Memory is what your teams’ runs have learned, so the next run starts knowing it. Andon keeps two kinds, split by what the memory is about: - [Recipes](https://andon-docs.pages.dev/guide/recipes.md): A recipe is how a card runs: what the agent is told, where it works (a new branch, a scratch folder), what it hands back, and what happens when it finishes. Every card has one. Most of the time Andon picks it for you; you change it when a card is a different kind of job, such as a question to study instead of code to write. - [Writing a recipe](https://andon-docs.pages.dev/guide/writing-a-recipe.md): Write a recipe when a kind of job keeps coming back and the built-ins don’t fit it: a video rendered with one tool, a release checklist, a migration your repository does the same way every time. A recipe is a prompt template plus the settings for where the run works and what it hands back. Owners and admins edit recipes. For what the built-ins do and how a card gets its recipe, see Recipes. - [Studies](https://andon-docs.pages.dev/guide/studies.md): Some requests are questions before they are work: is the Settings area finished?, why is the board slow on a phone?, what would it take to drop Orca? A Study answers one. It is a card with the Study recipe: its run reads the code, starts the app and walks it, asks you what it needs, and ends with a Proposal: what it found, with evidence, and the project and cards it suggests. You read the proposal on the card, steer it with comments the way you’d review a pull request, and Accept turns it into a project with its cards in the Backlog. - [Capture from anywhere](https://andon-docs.pages.dev/guide/capture.md): Capture puts a card on your board without opening it: share a link or a screenshot from your phone, say “add to board” to Siri, or press a hotkey on your Mac. In the desktop app, ⌃⌥⌘Space (Ctrl+Alt+Space on Windows and Linux) opens quick add from any app. Every capture becomes a card in the Backlog, owned by you, and its recipe is picked for you unless you name one. - [Integrations](https://andon-docs.pages.dev/guide/integrations.md): Connect Andon to the trackers and accounts your teams already use, so linked issues show their state on cards, issues can come in as cards, and Andon can update an issue as its card moves. Everything is under Settings → Connections. Everyone sees what is connected; owners and admins connect, change and disconnect. - [Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md): The import moves a team onto Andon from Trello, Jira, Linear or Asana in one go, with everything it has there: issues, sub-tasks, comments, files, statuses, people, sprints, versions and custom fields. You see a dry run of what it will make before anything changes, and you can run it again later: it updates what it made and never duplicates it. An Asana import can also stay in sync afterwards. - [People and roles](https://andon-docs.pages.dev/guide/people-and-roles.md): Invite people to your board, decide who can change what, and keep a team’s cards to the people on it. Everyone has one of three roles, and each role can do everything the ones below it can: ## Run machines and deploy - [Deploy Andon](https://andon-docs.pages.dev/machines/deploy.md): Deploy Andon when a team shares one board, or when the board has to stay up while your computer sleeps. An instance is one server, which also serves the board, and one Postgres 15 or newer from any provider. The code is the same on every host. - [The desktop app](https://andon-docs.pages.dev/guide/desktop-app.md): The desktop app is Andon in a window of its own on macOS, Windows or Linux. Use it to run Andon on your own computer with nothing to deploy, or to keep several Andon instances one keystroke apart. It loads each instance’s own board, so what you see is what a browser shows, plus what a browser tab can’t do: - [AI backends](https://andon-docs.pages.dev/machines/ai-backends.md): Andon calls a model for attention triage, the assistant, recipe detection, Autopilot’s placement, Start work’s guesses, the finish classifier (Auto-Done) and voice. Every one of those calls goes through one client, built on the Vercel AI SDK, which can send it four ways. Which one is a setting, not a deploy. - [Mac machines](https://andon-docs.pages.dev/machines/macos.md): Put the Andon agent on a Mac so it can run cards from your board. The machine is yours: it runs your cards, not other people’s. It runs as a LaunchAgent under your user and starts each time you log in. - [Linux machines](https://andon-docs.pages.dev/machines/linux.md): Put the Andon agent on a Linux desktop or server (Debian, Ubuntu, Fedora or Arch; x64 or arm64) so it can run cards from your board. The machine is yours: it runs your cards, not other people’s. The agent runs as a systemd user service. On a server, turn on linger so it keeps running when nobody is logged in. - [Windows machines](https://andon-docs.pages.dev/machines/windows.md): Cards run on macOS and Linux. The agent needs tmux, so it doesn’t run on Windows itself. It runs in WSL2, Windows’ built-in Linux, as the ordinary Linux agent (Linux machines). This page sets up an always-on Windows PC once, so that you can do the rest over SSH and the agent comes back after a reboot with nobody signed in to Windows. - [A NAS as a machine](https://andon-docs.pages.dev/machines/nas.md): A NAS that runs Debian underneath (UGREEN’s UGOS Pro, for one) can be an always-on Andon machine. It is a Linux machine (Linux machines) with three differences: the vendor owns the system packages, the board may be on your own computer, and the NAS may need its own route to a board it also hosts. - [Agent updates](https://andon-docs.pages.dev/machines/updates.md): The agent keeps itself on the build your board serves. It installs an update only when the build is signed with the release key this machine pinned. The installer pins one for you: your board’s own key when the board signs its builds, else Andon’s release key. When your board serves unsigned builds, a machine that trusts Andon’s key updates from Andon’s official releases instead. - [Remove a machine](https://andon-docs.pages.dev/machines/remove-a-machine.md): Take a machine off your board when you retire it, give it away, or enrolled it by mistake. Revoking it on the board cuts its access at once; uninstalling the agent on the computer stops it and clears its files. Do both. - [Orca or direct](https://andon-docs.pages.dev/machines/orca-or-direct.md): A machine runs each card in one of two places. With Orca installed, a run gets an Orca worktree and terminal. Without it, the machine runs in direct mode: a git worktree, and the coding agent in the agent’s own tmux. Orca is optional. - [One machine, several boards](https://andon-docs.pages.dev/machines/multiple-agents.md): A computer runs one Andon agent per board. To take work from a second board, add a second agent, called a profile, next to the first. Each has its own config, service, logs and updates. - [Accounts and model providers](https://andon-docs.pages.dev/machines/accounts-and-providers.md): A run has three parts you can choose. The agent is the CLI that does the work: Claude Code, Codex or Gemini CLI. The account is whose login it uses: a machine can hold several Claude, Codex and Gemini CLI logins, so a team can run on a work account while another runs on a personal one. The provider is the endpoint that serves the tokens, when it isn’t the account’s own: an API key for OpenRouter, say, or a local Ollama server. - [Harnesses](https://andon-docs.pages.dev/machines/harnesses.md): A harness is a versioned bundle of skills (SKILL.md procedures, with their references and scripts) plus an outline of the stages a card goes through. Use one to give a team’s runs your own process, rather than a prompt somebody retyped. A run records the harness it ran under by hash, so you can compare two runs: same harness, same model, a different outcome is a real difference. - [Andon drives](https://andon-docs.pages.dev/machines/drives.md): Andon drives is one switch that keeps the board going without you, overnight say. While it is on, Autopilot runs for every team, and Andon answers the questions and routine review steps that would otherwise wait for you. Every answer is on the run’s history with its reason, so you can read back what was decided for you. - [The use-andon skill](https://andon-docs.pages.dev/machines/use-andon-skill.md): The Andon agent installs a use-andon skill so the coding agents on the machine (Claude Code, Codex, Gemini CLI, Cursor, Hermes and the rest below) can use the andon CLI from any repository: add and steer cards, put a plan on the board, say what needs you, and check this machine’s agent. There is nothing to install by hand. The agent writes the skill at andon setup and syncs it every time it starts, which covers andon up, the desktop app, app updates and the agent’s daily self-update. - [Files on a machine](https://andon-docs.pages.dev/machines/files-on-a-machine.md): Andon puts files on a computer from four places: the board’s installer (install.sh), the desktop app, andon up and the agent itself. This page lists every one of them, who writes it, who reads it, and which one wins when two could apply. Read it when andon says something you don’t expect, before you move a folder to the Trash, or when a computer has both the desktop app and an installer-installed agent. ## Look something up - [The andon command](https://andon-docs.pages.dev/reference/cli.md): andon is the machine agent’s command line: it enrolls a machine with a board, runs the daemon, sets the machine’s policy, and reads and changes cards from a terminal. Run andon with no arguments (or andon --help) to print the same list in short. - [Machine policy](https://andon-docs.pages.dev/reference/policy.md): A machine’s local policy decides what Andon may do on it: which recipes run, how far a run’s permissions go, whether it merges, which agent CLIs it starts. The board can ask for anything; the machine’s policy is the last word. It lives in the policy object of the agent’s config file (agent config), and you change it on the machine with andon policy. In the desktop app, Settings → Machines has a button for each fix on the computer it runs on (desktop app). - [The agent's config file](https://andon-docs.pages.dev/reference/agent-config.md): Each machine’s agent keeps its settings in one JSON file, written by andon setup and changed by the andon commands. You rarely edit it by hand: use it to look something up, or to change a key that has no command. - [MCP tools](https://andon-docs.pages.dev/reference/mcp-tools.md): Each run’s agent session gets an MCP server named andon, started by the agent (andon mcp). Its tools are how a run talks to the board: it asks you a question, shows a preview, records what it learned, and reports at the end of a turn. In Claude Code they appear as mcp__andon__. - [The andon-server command](https://andon-docs.pages.dev/reference/server-cli.md): andon-server runs the portable server: the board, its API and its database migrations, on any Node host with Postgres. It reads its settings from the environment (environment variables). - [Environment variables](https://andon-docs.pages.dev/reference/env.md): The server takes all its settings from the environment. The agent takes almost none: its settings are in its config file, and the variables below only move folders, answer prompts or carry a run’s context. - [The public API and webhooks](https://andon-docs.pages.dev/reference/api.md): Scripts, CI and other tools read and write cards without the board. They use /api/v1 with an org’s API token, and webhooks tell them when something changes. The machine-readable contract is the OpenAPI 3.1 document at /api/v1/openapi.json. This page is the readable one, and a test (apps/server/test/api/docs.test.ts) fails when the two disagree. - [The capture endpoint](https://andon-docs.pages.dev/reference/capture-api.md): The capture endpoint adds a card to your board from anywhere: a phone shortcut, a launcher script, andon add. It takes a personal capture token, so the card is yours, and puts it in the Backlog. - [Repository settings (.andon/settings.json)](https://andon-docs.pages.dev/reference/repo-settings.md): A team’s automation settings can live in its repository, so every Andon instance with a clone of that repository uses the same ones. Andon creates the file. What you change in Andon afterwards is an override for that instance only: Andon never rewrites the file. - [The .andon/ directory format](https://andon-docs.pages.dev/reference/andon-directory.md): .andon/ at a repository’s root is what the repository remembers: conventions, decisions, traps and how-tos, longer notes, and the plans of its projects. It is committed beside the code, so every clone, tool and Andon instance reads the same files. This page is the file format. The schemas are in packages/shared/src/andon-directory.ts. - [Who can do what](https://andon-docs.pages.dev/reference/permissions.md): Andon has three roles in an org, ranked member < admin < owner. Each role can do everything the roles below it can: ## Change Andon - [Set up from zero](https://andon-docs.pages.dev/contributing/setup.md): This page takes a computer with nothing installed to a clone of Andon whose checks pass. Do it once. After that, Local development covers the daily loop: pnpm dev and pnpm dev:demo. - [Local development](https://andon-docs.pages.dev/contributing/local-development.md): Run Andon from a clone to change it: the server and the board with hot reload, a seeded demo org, and a machine that runs cards against fake coding agents. You need Node 22 and pnpm 10, and no Supabase: every dev command and test suite runs on this worktree’s own Postgres (pnpm db:local, started for you). Docker is needed only for the container checks. Set up from zero lists every tool, and which work needs it. - [Architecture](https://andon-docs.pages.dev/contributing/architecture.md): Read this before your first real change to Andon. Most of the code follows from one decision: the database is the message bus, and every machine dials out to it. When a bug makes no sense, it is often a property of that shape. - [Testing](https://andon-docs.pages.dev/contributing/testing.md): Andon has nine Vitest projects and a Playwright suite. Most of them need nothing running; the rest need only this worktree’s own Postgres, which they start themselves. Run the cheap ones constantly and the heavy ones on purpose. - [Schema changes](https://andon-docs.pages.dev/contributing/schema-changes.md): A change to a table, column, policy, RPC, view, trigger or setting is one migration file in db/migrations/, the only source of Andon’s schema. The server applies it on every Postgres it runs on: andon up, the desktop app, Vercel with Neon, a self-hosted server. The mechanics of db/ (the frozen baseline, upgrading old databases, what the schema names mean) are in db/README.md. - [The server](https://andon-docs.pages.dev/contributing/server.md): apps/server is Andon’s backend, on any Postgres 15+: sign-in, a data API, live updates, file storage, the functions and the scheduled work. Read this before you change it. Its routes, entry points and tests are in its README; the schema side is in db/README.md. - [Design system](https://andon-docs.pages.dev/contributing/design-system.md): Read this before you change what the board looks like or how fast it loads. The spec itself, with the tokens, type scale, components and motion values, is DESIGN.md at the repository root. Who uses Andon, and on which devices, is in PRODUCT.md. - [Writing docs](https://andon-docs.pages.dev/contributing/writing-docs.md): Read this before you add or change a page under docs/. It applies to people and agents alike. - [The docs site](https://andon-docs.pages.dev/contributing/docs-site.md): apps/docs is the Andon docs site: an Astro Starlight app, themed as “Aquarium”. It renders the Markdown pages in docs/ as they are, so the pages you maintain here are the site. docs/internal/ stays off it. - [Board data: planning and organising](https://andon-docs.pages.dev/contributing/board-data.md): How the features in the guide’s planning and organising pages are stored and enforced. Read it before you change one of their tables, triggers or RPCs. Each table’s migrations are under db/migrations/. The user side is in docs/guide/. - [Start work internals](https://andon-docs.pages.dev/contributing/start-work.md): How the Start work box reads a request, and which model calls it makes. The user’s guide is Start work. - [Preview internals](https://andon-docs.pages.dev/contributing/previews.md): How a preview reaches the board, and what the review tools may do. The user’s guide is Previews and annotations. The design and its decisions are in the review-on-the-preview spec. - [Integrations internals](https://andon-docs.pages.dev/contributing/integrations-internals.md): How connections are stored, how write-back and Linear’s comments run, and how the one-time tracker import works, for people changing that code. The user guides are Integrations and Import from a tracker. - [Memory internals](https://andon-docs.pages.dev/contributing/memory-internals.md): Andon keeps two kinds of memory, and a run can get both: here are the tables, the files, how a run’s slice is chosen and how each writer proposes. What people see and do with memory is in the user guide (Memory); the file format of .andon/ is in the reference. - [Study proposals and run pages](https://andon-docs.pages.dev/contributing/run-sandboxing.md): How a study’s proposal is stored and accepted, and how a page a run publishes is kept from reaching the board, for people changing that code. How a study is kept from pushing, and its mock folder, are in How a study is kept from pushing. The user guides are Studies and Recipes. - [How a study is kept from pushing](https://andon-docs.pages.dev/contributing/study-sandbox.md): A study is a run that answers a question instead of changing code: it reads, runs the app, asks through Needs you and ends with a proposal (Studies). It must never push a branch or open a pull request, whichever agent runs it. Keep every layer below when you change the launch path. The code is apps/agent/src/study.ts, and its header says the same in short. - [Voice providers](https://andon-docs.pages.dev/contributing/voice-providers.md): Voice in the chat (the mic beside Send, calls, car mode) is a speech-to-speech session: the browser streams the mic to a realtime model, the model speaks back, and everything it is asked goes to the chat’s orchestrator through one function, ask_orchestrator. Which model, and through whom, is a voice provider. Two are built in: - [Releasing the desktop app](https://andon-docs.pages.dev/contributing/desktop-release.md): How to sign a Mac build by hand, and how a tagged release builds every platform and reaches installed apps. Building and running the app from a checkout is in its README; installing and using it is The desktop app. Paths to scripts/ and src-tauri/ below are under apps/desktop/. - [Docs components](https://andon-docs.pages.dev/contributing/docs-components.md): The components an MDX page on the docs site can use by name, each shown working, with the lines that make it. Pages in docs/ are plain Markdown and don't need them. - [Mac machines](https://andon-docs.pages.dev/guides/mac-machines.md): Put the Andon agent on a Mac so it can run cards from your board. It runs as a LaunchAgent under your user and starts each time you log in. - [Needs you](https://andon-docs.pages.dev/concepts/needs-you.md): Needs you is the list of everything waiting for a person. Work through it and the agents keep going. - [Machine policy](https://andon-docs.pages.dev/reference/machine-policy.md): A machine's local policy decides what Andon may do on it. The board can ask for anything; the machine's policy is the last word. Change it on the machine with andon policy.