Documentation·Get Started
Get Started

Installation

Most people are up and running in fifteen minutes. Everything runs on your machine — no account, no cloud-side setup, no "bring your own Kubernetes" step.

Requirements

  • macOS 13+, Windows 11, or Ubuntu 22.04+.
  • Node.js 20 or newer (20 LTS is fine).
  • At least 8 GB of RAM and ~1 GB of free disk for the app plus its store.
  • A working Codex CLI install — see below.

Install Codex CLI

SenateLab drives your coding CLI rather than replacing it. Install the Codex CLI first, then point SenateLab at it on first launch.

npm install -g @openai/codex-cli

Alternatively, grab it from the official page at openai.com/codex and follow the installer. SenateLab treats any OpenAI-compatible CLI as a valid engine, so if you prefer a self-hosted binary, that works too.

Download SenateLab

Go to the download page, grab SenateLab_1.3.18_aarch64.dmg, open it, and drag the SenateLab icon into your Applications folder. Windows and Linux builds are cut from the same release tag — if you do not see your platform, it is in the roadmap.

First launch

The first launch shows a short onboarding flow. You paste the path to your Codex CLI binary (or let the app auto-detect it), choose a default provider (OpenAI-compatible, Ollama, or custom), and run a one-click connection test. Once the test goes green, SenateLab seeds a default map and five example agents so you are not staring at a blank canvas.

Check it works

From any terminal:

senatelab doctor

The command prints a short status report: CLI path, database path, provider reachability, keychain access. When everything is healthy you see all checks passed at the bottom. If anything fails, the output tells you exactly which step to fix.

Where data lives

  • macOS: ~/Library/Application Support/SenateLab/
  • Windows: %APPDATA%\SenateLab\
  • Linux: ~/.config/SenateLab/

Inside you will find a single SQLite file (senatelab.db, WAL-mode) with every workspace, agent, message, and report. Provider API keys are never stored in that file — they live in the OS keychain and are referenced by id. Deleting the folder resets the app to a fresh state.

Updates

SenateLab checks for new releases on launch and offers a one-click update when one is available. Under the hood it pulls signed artifacts from the GitHub Releases page for the repo. If you prefer to drive this manually, open the app menu and pick Check for updates…. Updates are always optional — a version you have tested is yours to keep.