Installation · CommonOS

CommonOS needs two things: the cos command and a PostgreSQL server. cos ships as a single prebuilt file for macOS and Linux, so you don’t need Rust. CommonOS is tested on PostgreSQL 18 and works with 14 or later.

Install cos

Terminal

curl -fsSL https://github.com/ten-year-forge/CommonOS/releases/latest/download/install.sh | sh

The script picks the build for your system, checks its SHA-256 checksum, and puts cos in ~/.local/bin. If that folder isn’t on your PATH, the script prints the line to add.

While the repository is private

GitHub only serves release files to accounts that can see the repository. Install the GitHub CLI, log in, and fetch the script through it. The script then downloads cos through the GitHub CLI too.

Terminal

gh auth login
gh release download --repo ten-year-forge/CommonOS --pattern install.sh --output - | sh

Start PostgreSQL

Pick one. Docker is the quickest way to get the latest version without touching your system packages.

Terminal

docker run -d --name commonos-pg --restart unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_USER="$USER" \
  -e POSTGRES_DB=commonos \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  -v commonos-pgdata:/var/lib/postgresql \
  postgres:18

This also creates the commonos database. The superuser has your login name, so the default database URL works without a password. Trust auth is safe here only because the port is bound to 127.0.0.1.

Terminal

brew install postgresql@18
brew services start postgresql@18
echo 'export PATH="$(brew --prefix postgresql@18)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
createdb commonos

Terminal

sudo apt install postgresql
sudo -u postgres createuser --superuser "$USER"
createdb commonos

There is no migrate step. cos creates its tables when it starts.

Check it works

Terminal

cos --version
cos serve --mock

cos serve --mock connects to the database, creates the tables and starts the dashboard at http://127.0.0.1:9120. With no profiles yet, it warns no profiles in ~/.commonos and keeps running. Stop it with Ctrl+C, then go on to Basic Usage.

Supported systems

System	Build
macOS, Apple Silicon	`aarch64-apple-darwin`
macOS, Intel	`x86_64-apple-darwin`
Linux, x86_64	`x86_64-unknown-linux-musl`
Linux, ARM64	`aarch64-unknown-linux-musl`

The Linux builds are static, so they run on any distribution. Windows isn’t supported yet; use WSL.

Install options

The script reads these environment variables:

Variable	Default	Does
`COS_VERSION`	the latest release	Install a given release, such as `v0.1.0`
`COS_INSTALL_DIR`	`~/.local/bin`	Where to put `cos`
`COS_DOWNLOAD_URL`	GitHub Releases	A mirror holding the release archives

Terminal

curl -fsSL https://github.com/ten-year-forge/CommonOS/releases/latest/download/install.sh | COS_VERSION=v0.1.0 COS_INSTALL_DIR=/usr/local/bin sh

Install by hand

Each release has one archive per system, a .sha256 file for each, and a combined SHA256SUMS. To install without the script:

Terminal

curl -fLO https://github.com/ten-year-forge/CommonOS/releases/latest/download/cos-aarch64-apple-darwin.tar.gz
curl -fLO https://github.com/ten-year-forge/CommonOS/releases/latest/download/cos-aarch64-apple-darwin.tar.gz.sha256
shasum -a 256 -c cos-aarch64-apple-darwin.tar.gz.sha256
tar -xzf cos-aarch64-apple-darwin.tar.gz
mv cos-aarch64-apple-darwin/cos ~/.local/bin/

Upgrade and uninstall

To upgrade, run the install script again. It replaces cos with the latest release.

To uninstall, delete the command. Your profiles and data stay until you remove them too:

Terminal

rm ~/.local/bin/cos
rm -rf ~/.commonos       # profiles, keys, commonos.toml, pricing.toml
dropdb commonos          # every session, message and cost record

How cos finds the database

cos connects to postgres:///commonos unless you set COMMONOS_DATABASE_URL or pass --database-url. That URL has no host or user, so the driver fills them in:

Host: a local Unix socket if one exists, otherwise localhost:5432. A Docker container has no socket on the host, so it uses localhost:5432.
User: your login name, unless PGUSER is set.

Any standard Postgres URL works:

Terminal

export COMMONOS_DATABASE_URL=postgres://commonos:secret@db.internal:5432/commonos

Troubleshooting

Problem	Fix
`cos: command not found`	`~/.local/bin` isn’t on your `PATH`. Add the line the script printed, then open a new terminal.
`could not download …`	The repository is private or the release is missing. Use the GitHub CLI, as above.
`checksum mismatch`	The download was damaged or changed. Run the script again; if it repeats, don’t install that file.
`connection refused` or `pool timed out`	Postgres isn’t running. Start the container or the service.
`role "…" does not exist`	The database user doesn’t match your login. Create it, or put the user in the URL.
`Address already in use` on port 9120	Another `cos serve` is running. Stop it or pass `--port 9121`.

Build from source

You only need this to change CommonOS itself or to add a plugin, because plugins are compiled into cos. You’ll need Rust (stable) and a second database for the tests:

Terminal

git clone https://github.com/ten-year-forge/CommonOS.git
cd CommonOS
cargo install --path crates/commonos-cli
createdb commonos_test
COMMONOS_TEST_DATABASE_URL=postgres:///commonos_test cargo test --workspace

See CONTRIBUTING.md in the repository for the checks to run before you push.