02 β Getting started
Install
One command for macOS and Ubuntu. The installer handles Python, Docker, and the costaff CLI.
# macOS or Ubuntu
curl -fsSL https://raw.githubusercontent.com/costaff-ai/costaff/main/install.sh | bash
What the installer does
- Detects the OS β macOS or Ubuntu/Debian. Other distros exit with an error.
- System packages β Xcode Command Line Tools + Homebrew on macOS;
aptpackages on Ubuntu. - Python 3.12 β Homebrew on macOS,
deadsnakesPPA on Ubuntu (Ubuntu 24.04+ is handled β the retireddistutilspackage is skipped automatically). - Docker β Docker Desktop on macOS, Docker Engine on Ubuntu. On macOS the installer launches Docker Desktop and waits for the daemon (up to 90s); on Ubuntu it starts the daemon via systemd if it's stopped.
- Repo β clones
costaff-ai/costaffinto~/.costaff/costaff/. - Virtualenv β creates
~/.costaff/.venv/and runspip install -e. - PATH β appends the venv to
~/.zshrc(macOS) or~/.bashrc(Ubuntu). - Setup wizard β when no manual steps remain (e.g. no Docker group re-login needed), the installer chains straight into
costaff onboard.
Ubuntu: docker group
The installer adds you to the docker group. You won't be able to run docker without sudo until you log out and back in (or run newgrp docker in a fresh shell). Do this before the next step.
Verify the CLI is on PATH
source ~/.zshrc # or ~/.bashrc on Ubuntu
costaff --version
You should see a version string. If you get command not found, check that $HOME/.costaff/.venv/bin is in your PATH and reload your shell config.
Re-running the installer
The installer is idempotent β running it again on an existing install will git pull the repo and reinstall the CLI. It won't touch ~/.costaff/costaff/.env or your registered agents.