MAC APPDownload the app.
For Apple silicon Macs on macOS 15 or later. You also need Tailscale running, a Git repository and an Anthropic or OpenAI API key. Sign in to the GitHub CLI (gh auth login) too: Ace names people by their GitHub login, checks who can see a GitHub project with it, and lists its issues and pull requests. No checkout, Bun or terminal required.
Open the disk image and drag Ace into Applications, then open it.
On first launch, Welcome to Ace asks for your key. It’s checked, then saved in your keychain; the app never sees it again. Add more later in Settings → Providers (⌘,).
Press ⌘O and choose a folder to add it as a project. Then start a channel from the project’s dashboard or sidebar.
Closing the window leaves Ace Helper running in the background, so your channels stay available. Settings → Ace Helper shows Git, shell, GitHub CLI and Tailscale status, a QR code for opening this Mac from your phone, and starts, stops or restarts the helper.
The app ships the ace command line too. Choose Settings → Ace Helper → Command line tool → Install to link it into ~/.local/bin (ace-canary for Canary). It follows app updates and talks to the app’s own host, so no checkout is needed.
Ace checks for updates every six hours and asks before it installs one. Canary builds are published alongside as pre-releases, with a yellow icon and their own data.
SOURCERun from source or a fork.
Use this to change Ace, or to run it on a machine the app doesn’t support. You need Bun 1.4 or later, Git, Tailscale running and a model provider key. Clone your fork instead to make Ace your team’s own.
Clone and install.
git clone https://github.com/githubnext/ace && cd ace bun install
Save a key, then start a channel in your project.
bun ace key set ANTHROPIC_API_KEY bun ace new --project ~/code/my-repo
Start the host and open the app in your browser.
bun app build && bun ace serve bun ace open
Run bun desktop dev for the desktop app from source. It keeps its own settings, keys and channels, apart from the installed app.
bun ace serve share a data directory, keychain and port. Don’t run both on one machine at the same time.Every command is listed under commands.
TEAMSWork as a team.
Both ways work the same once they’re running. A team is a tailnet: everyone on it who runs Ace is on your team, with nothing to join. To add someone, add them to your tailnet in the Tailscale admin console.
That’s enough to see and join teammates’ channels while their Macs are awake, in projects you can both see. A directory keeps sleeping hosts’ channels listed, keeps project shares, and shows who’s here.
RECOMMENDEDAdd a team directory.
The directory lists your projects, hosts and channels, keeps project shares, and its project lobbies carry presence: who’s here and who’s away. It holds no channel content. One Mac on your tailnet serves it; pick one that stays on, like a Mac mini.
On that Mac, choose Create directory → This Mac, from the sidebar’s Team directory card or Settings → Team.
That’s it. There’s no account or secret: every other Mac on the tailnet finds the directory and joins it on its own. Settings → Team lists the hosts in it and when each last synced.
Stop serving… in Settings → Team turns it off and deletes its project shares. While the Mac serving it is offline, teammates keep working; their sync errors name that Mac.
OPTIONALOr deploy the directory.
HOSTED BY YOUR TEAM‡A team can deploy its directory as a service instead, so it doesn’t depend on one Mac. Hosts reach it with a shared team secret.
From the app: Team setup, at the bottom of the sidebar, then Get your team started deploys it to your Cloudflare account with your own
wrangler login, and joins it. Or, from a checkout, one command deploys it to Cloudflare or Fly.io and prints its address and the secret.‡bun services/deploy.ts cloudflare # or fly
Share the address and the secret with your team privately, or send the invite from Settings → Team → Invite…. Teammates join from Settings → Team → Join…, or use Ask to join beside your Mac in Team setup, which you approve. Ace checks both before it saves the secret to their keychain.
From the CLI, ace key set ACE_SECRET and ace directory <url> do the same.
NEW · BETARun channels in the cloud.
OPTIONAL · HOSTED BY YOUR TEAM‡A cloud channel keeps its conversation in your team’s own account and runs its tools in a Linux container there, so it keeps working while every laptop is closed. Ace runs no service for this; you deploy and pay for it.
Deploy the compute service once, with Docker running. Give it the team secret,
ACE_SECRET(a deployed directory’s, or a new one fromopenssl rand -hex 32that each host saves withace key set ACE_SECRET), andTAILNET, your tailnet’s MagicDNS suffix. Model and GitHub keys are its secrets; the container never sees model keys.‡cd services/compute bunx wrangler login bun run deploy bunx wrangler secret put ACE_SECRET bunx wrangler secret put TAILNET bunx wrangler secret put ANTHROPIC_API_KEY bunx wrangler secret put GITHUB_TOKEN
Turn on Settings → Beta → Cloud compute and save the service’s address. A deployed directory can name it for every host instead.
Start a channel in a GitHub project and choose Run in cloud. It opens once its container is ready. To move an existing channel there, choose Move to cloud workspace from its menu; its agent commits and pushes its lanes first, and it can’t move back.