Install Bernstein¶

What this page does: Gets Bernstein installed on your machine, then verifies it runs. Time: ~2 minutes (the install) + ~30 seconds (the check).

When you're done, bernstein --version will print a version number and you'll be ready to follow the first-run walkthrough.

Requirements¶

• Python 3.12 or later. python3 --version to check.
• Git (any recent version). Bernstein uses git worktrees to isolate agents.
• macOS, Linux, or Windows.

That's it for installing. Before your first run you will also need at least one CLI coding agent (Claude Code, Codex CLI, Gemini CLI, ...) and its API key - the first-run walkthrough covers that. You do not need them to complete this page.

Supported platforms¶

Windows notes:

• Worktree directory sharing via symlinks (node_modules, .venv) requires Developer Mode or Administrator privileges; without it, agents fall back to per-worktree installs.
• Deep worktree paths are handled with extended-length path support; no registry changes are needed.
• Forced agent stops are recorded in the audit chain with the same receipt format on every platform, so run histories verify identically across mixed-OS teams.

Recommended: uv tool install¶

uv installs Bernstein into an isolated tool environment. Single command, no venv to manage.

uv tool install bernstein

If you don't have uv:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
irm https://astral.sh/uv/install.ps1 | iex        # Windows PowerShell

Other install methods¶

pipx install bernstein

pip install bernstein

brew install chernistry/tap/bernstein

docker run -v "$(pwd)":/workspace -v "$(pwd)/.sdd":/workspace/.sdd \
  -p 8052:8052 ghcr.io/sipyourdrink-ltd/bernstein -g "your goal"

git clone https://github.com/sipyourdrink-ltd/bernstein
cd bernstein
uv venv && uv pip install -e .
source .venv/bin/activate
bernstein --version

Run without installing¶

• uvx bernstein - downloads the latest release into a temporary environment and runs it. Needs uv.
• npx bernstein-orchestrator - Node wrapper that delegates to an existing Python setup. It does not install Bernstein: it requires Python 3.12+ and pipx or uv on $PATH, then runs Bernstein through them.

One-liner installers¶

On a machine that already has Python 3.12+, the install scripts set up pipx and Bernstein in one step. They check for Python 3.12+ and stop with an error if it is missing - they do not install Python itself.

curl -fsSL https://bernstein.run/install.sh | sh           # macOS / Linux
irm https://bernstein.run/install.ps1 | iex                # Windows PowerShell

Script source: install.sh · install.ps1.

Optional extras¶

The base install stays small. Pull in provider SDKs only when you need them:

Combine extras with brackets: pip install 'bernstein[openai,docker,s3]'.

Editor extensions¶

• VS Marketplace
• Open VSX

Verify it worked¶

bernstein --version

You should see the current release version. Then run the pre-flight check:

bernstein doctor

doctor checks your setup end to end: installed agent CLIs (adapters), API keys, port availability, the .sdd workspace, and supporting tools.

Straight after an install - before you have configured an agent CLI or an API key - expect red rows for adapters, auth, the workspace, and "Ready to run", and a non-zero exit code. Those clear as you work through the first run. At this stage you only need bernstein --version working and the Python and port checks green. Each failing row names the step to fix.

command not found: bernstein Your tool bin directory is not on $PATH. Add it:

• uv / pipx: export PATH="$HOME/.local/bin:$PATH" (and add to ~/.zshrc / ~/.bashrc)
• Windows: re-open PowerShell after install - pipx adds the path on first run.
• macOS Homebrew: run brew doctor and follow the PATH advice.

Next¶

Now that bernstein --version works, head to First run to take it from "installed" to "your first orchestrated task complete" in about 5 minutes.

For platform-specific notes, see also:

• Linux install (COPR / Homebrew / pip / Docker)