onebox

Guide 03 of 27

For your agent: .md · all guides

On this page
  1. What it costs
  2. On your Mac
  3. On your box
  4. Check it works
  5. Common errors

Command-line tools: your Mac and your box

Runs on: your Mac, and your box (over SSH).

The skills call command-line tools (CLIs). Most of them go on your Mac. The box needs almost nothing from you: box:box-setup installs what it needs. This page lists each tool, which skill needs it, and how to install it.

What it costs

All tools here are free. The Mac tools take about 15 GB of disk with Xcode and one Simulator runtime, and more for Docker images.

On your Mac

Install Homebrew first. Most of the tools below come from it.

Everyone needs these

ToolWhyInstall
XcodeiOS builds, the Simulator, xcodebuild, xcrunxcode.md. The full Xcode, not only the Command Line Tools.
gitevery repocomes with Xcode
Node.js 22 or 24 (LTS)the skills’ scripts, Expo, easbrew install node@22, or a version manager such as fnm
pnpmthe package manager in a /start:new-app repocorepack enable, then corepack install -g pnpm@10. Corepack comes with Node. In a repo it runs the version that package.json pins in packageManager. Outside a repo it runs the global one; its default, pnpm 12, does not start through corepack yet.
jqreads the onebox configbrew install jq
easExpo builds and updates, also local buildsnpm install -g eas-cli. See expo-eas.md.
CocoaPods (pod)local iOS buildsbrew install cocoapods. See xcode.md, step 6.
fastlaneeas build --localbrew install fastlane

Only for some skills

ToolNeeded byInstall
Docker (Docker Desktop, OrbStack or Colima)dev:test-loop and the API tests (a real Postgres)the Docker Desktop or OrbStack app, or brew install colima docker
.NET SDK 10 or newera .NET APIbrew install --cask dotnet-sdk
gh (GitHub CLI)box:box-setup (the runner token), box:staging-envbrew install gh, then gh auth login
sshevery box skillcomes with macOS. Make a key: see vps.md, step 1.
python3ship-ios:app-store-screenshots (contact sheets, with Pillow)comes with Xcode. Then python3 -m pip install --user Pillow.
Playwright and sharpship-ios:app-store-screenshots (rendering)mkdir -p ~/.cache/onebox-render && cd ~/.cache/onebox-render && npm i playwright sharp
ffmpegcontent:video (chained shots)brew install ffmpeg
hcloudrenting a Hetzner VPSbrew install hcloud. See vps.md.
Tailscalereaching the box from anywherethe app from the Mac App Store. See remote-access.md.

Your secrets tool, one of these

Pick one in secrets.md. You need only that one.

secrets.toolInstall
envnothing
dopplerbrew install dopplerhq/cli/doppler, then doppler login
1passwordbrew install --cask 1password-cli, then turn on the CLI integration in the 1Password app

On your box

Start from Ubuntu Server LTS, x86_64. You need only an SSH login with your key:

Then run box:box-setup from your Mac. It installs the rest over SSH: the admin user, curl, jq, ufw, unattended-upgrades, restic, python3-yaml, Docker with the Compose plugin, Traefik and cloudflared. Do not set up Traefik or cloudflared by hand first. The setup refuses a box that already runs a tunnel or a proxy it did not set up.

Two more, and only if you want them:

You never install Node, .NET or Postgres on the box. They run inside Docker images.

Check it works

On your Mac:

xcodebuild -version && node -v && pnpm -v && jq --version && eas --version && pod --version && fastlane --version

Each line prints a version. With an API, also docker info and, for .NET, dotnet --version.

On the box, after box:box-setup, its check phase must end with 0 fail.

Common errors

Wrong or out of date? Fix it on GitHub.