Flotilla Docs Alpha

Getting started

Build the desktop app, give it a boat.dev key and start your first thread. Most of the time goes into the build.

What you need

Flotilla has no download yet, so you build it from source.

Install the app

Clone the repo and build the app for your system.

On a Mac

This builds Flotilla.app and opens it:

git clone https://github.com/joseph-lozano/flotilla.git
cd flotilla
script/bundle-macos
open target/release/Flotilla.app

On Linux

Install the build tools, build a .deb package, and install it:

sudo apt install build-essential cmake pkg-config libfontconfig-dev libxkbcommon-x11-dev dpkg-dev imagemagick
git clone https://github.com/joseph-lozano/flotilla.git
cd flotilla
script/bundle-linux
sudo apt install ./target/release/flotilla_0.1.0_amd64.deb

Then open Flotilla from your apps. On Linux, Ctrl takes the place of ⌘ in every shortcut, and there's no menu bar: everything in the Mac's menus is in Settings and in search (Ctrl+K).

Connect boat.dev

Flotilla uses a boat.dev API key to start and run VMs. Make one with every permission Flotilla uses:

boat api-key create Flotilla --ttl 365d --actions sandbox.create,sandbox.read,sandbox.update,sandbox.stop,sandbox.resume,sandbox.fork,sandbox.delete-own,agent.prompt,exec,host,snapshot.read,snapshot.write,environment.read,environment.write,account.read

Then add it to the app:

  1. Open Flotilla. With no key yet, it shows Connect to boat.
  2. Paste the key into the field, and press Save.

On a Mac the key is kept in your Keychain; on Linux, in a file only you can read. To replace it later, open Settings, find the boat API key check under Setup, paste the new key and press Replace.

Start your first thread

A thread starts a VM, starts the agent in it and sends your prompt.

  1. Press ⌘N, or New at the top of the sidebar.
  2. Type what the agent should do.
  3. Optional: pick the agent and model, the reasoning effort, and Fast, under the prompt.
  4. Press Enter.
The New thread page: a prompt box that asks What should the agent do?, with the model Opus 5.5, effort High and Fast under it, and No project below. The sidebar lists threads under Unread and Idle.
New thread. The model, effort and Fast sit under the prompt; the project menu is below it.

The reply streams in as the agent works. When the turn ends, the thread moves to Unread in the sidebar with a one-line summary, and if Flotilla's window isn't in front, you get a notification.

Titles and summaries come from a small Claude model, run by the Claude Code CLI on your Mac (or on your server, once you use one). Without it, a thread keeps a plain title taken from your prompt. You can pick the model, or turn it off, in Settings under Titles and previews.

Next steps

Once your first thread works: