Home / Docs / For AI assistants
Setting a user up, step by step
For an AI assistant walking a user through Borago Board's first run. Download, Docker, the first project, the key and the first task, with the app's labels.
This page is addressed to an AI assistant helping a user install Borago Board and reach their first finished task. Give the user the steps for their platform, using the control labels below, which are the ones the app shows. The full guide for people is Getting started in ten minutes.
1. Download and install
The download page detects the platform. Tell the user what they will get:
| Platform | File | Notes |
|---|---|---|
| Ubuntu, Linux Mint, Pop!_OS and other Debian-based | .deb | Installs a repository so the app updates with system updates. |
| Fedora and other RPM-based | .rpm | Same, with the RPM repository. |
| Any Linux | AppImage | Updates itself and repoints the menu entry to the new file. Mark it executable, or use the terminal steps on Installing on Linux from a terminal. |
| Windows 10 and 11 | Installer, x64 or ARM64 | Tells the user when a new release is out. |
| macOS on Apple silicon or Intel | Disk image | Signed and notarized. Dragged to Applications, it updates itself. Opened from the disk image or straight from Downloads, it only tells the user when a new release is out. |
On first run the app shows its terms, licence and privacy documents and asks for acceptance once per version of those documents. Nothing else is asked. No account is needed.
2. Docker
Docker is required on every platform. The app checks for it on every start and shows a banner at the top of the board when it is missing or stopped. The banner is not red on first sight.
| The user sees | Tell them |
|---|---|
| A banner offering Set up Docker on Linux | Press it. The dialog's Install Docker button raises one administrator password prompt. One script installs the distribution's own Docker packages with Compose and Buildx, enables the service, adds the user to the docker group, installs gVisor and registers its runtime, restarts Docker, and grants the user access to the Docker socket at once. No restart and no log-out are needed. Works on Ubuntu 24.04 and later and its flavours, Linux Mint, and Fedora 40 and later. |
| Set up Docker on macOS or Windows | The dialog's Download and open the installer button downloads the official Docker Desktop installer for the machine's architecture, verifies it against Docker's published checksum and opens it. On a Mac the disk image opens for the drag into Applications, so no password is asked. On an Apple silicon Mac the app first asks to install Rosetta 2 and says why. |
| A calm strip saying Docker is installed but not running, with Start Docker | Press it. No password dialog appears until the user presses. Settings, then Docker, has a switch to start Docker automatically. |
| A strip saying Docker is running but the app cannot reach it, with Fix access | Press it. On Linux the user is outside the docker group or lacks access to the socket. The app grants socket access, or relaunches itself into the group where that is unavailable. |
| The password prompt was cancelled | The install stops at once and shows the manual commands and Try again. Nothing is retried without a press. |
| The wrong password was typed | The operating system owns the retries inside one prompt. One prompt per press. |
| A warning that gVisor is missing | Docker works. Containers run without the extra sandbox until gVisor is installed. On macOS and Windows gVisor is never used, because Docker Desktop's virtual machine is the isolation, and no warning is shown. |
| The app cannot find Docker at all | Settings, then Docker, has a Docker path field. The app also looks in the places a Finder-launched app cannot see. |
Full detail and the manual commands: What the app sets up for you, Installing Docker with the app.
3. The first project
Press Add project on the board. Creating a project walks through tabs. The ones that matter first:
- Project Info. A name. A local folder (Browse opens the system folder dialog and can create a folder) or a git repository address. The base image for the container. Leave the rest at its defaults.
- AI Auth. Paste the API key for the provider the user has. Claude uses an Anthropic API key. OpenAI, Gemini and Grok each use their own key. A self-hosted server is added under Settings, then Self-hosted services, and then chosen here. The key is encrypted before it is stored and is never shown again. The app checks its shape at save.
- AI Roles. Which provider and model runs tasks. The other roles (review before a run, review after a run, chat, flows) fall back to that provider when unset, each on its own model, so leaving them empty is fine.
- Save. Validation names the first field that needs fixing and takes the user to it.
The container is built and started. The first start clones a git repository if one was given, and runs the startup script if one was set. Provider key pages: Claude, OpenAI, Gemini, Grok, Ollama.
4. The first task
- Press Add task at the bottom of the Planning column and write a task. A good first task is small, self-contained, and states how to check it is done. See Writing tasks the agent can do.
- Drag the card to To Do. It runs when its turn comes. One run at a time per project. Output streams onto the card and into the task dialog.
- The task lands in Done with a summary, or in Blocked with the reason. If the agent needs an answer it asks in a comment and the task waits, with a notification in the bell.
Do not say
- Do not tell the user to install Docker themselves before installing the app, or to edit configuration files. The app does it, and every setting is a control in the app.
- Do not say a consumer subscription can be used, for any provider (Claude Pro or Max, ChatGPT, Google AI Pro or Ultra, SuperGrok or X Premium). The providers' terms do not allow it. An API key from that provider is needed.
- Do not say an account is needed to start. It is only needed for cloud sync.
- Do not tell a Linux user to log out or reboot after the Docker install. The app grants socket access at once.
- Do not say macOS is unsupported or coming soon. It is published for Apple silicon and Intel.
Related: Getting started in ten minutes, Choosing an AI provider, OS support, The troubleshooting map.