Field guide
Setting up a computer for NovaOS
Install Python, Docker, novaos-cli and the SDK on macOS, Linux or Windows; version matrix and install pitfalls.
What you need
| Component | Version | Why | Needed for |
|---|---|---|---|
| Python | 3.12+ (3.13 fine) | SDK requires >=3.12 | always |
| novaos-agent-sdk | 2.1.0 (docs) or 2.3.1 (latest) | agent runtime + clients | always |
| novaos-cli | >= 2.2.1 | scaffold, validate, publish, logs | publish |
| Docker (+ buildx, running) | recent | publish builds a linux/amd64 image | publish |
| Node.js | 18+ | npm install of the CLI; TypeScript MCP servers | optional |
| Git | any | version control | optional |
SDK versions: 2.0.0 (first A2A), 2.1.0, 2.3.0, 2.3.1 (latest; same code as 2.3.0). There is no 2.2.x of the SDK. CLI 2.2.0 and 2.2.1 are the same CLI. CLI 0.3.0 and older REJECT A2A manifests.
macOS
- Homebrew (asks for your password, run it yourself):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)", then run the two "Next steps" lines it prints. Needs Command Line Tools (xcode-select --install; macOS 15 -> CLT 16, macOS 26 -> 26, macOS 27 -> 27). brew install python@3.13 node gitbrew install --cask docker, open Docker Desktop once, wait for "Engine running".brew install orbitronai-repo/novaos/novaos-cli(ornpm install -g novaos-cli).- Check:
novaos-cli version(NOT--version: that flag errors;-Vworks).
Linux (glibc: Ubuntu/Debian)
sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip git- Node 20:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs - Docker:
curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker $USER(log out/in). npm install -g novaos-cli(or Homebrew on Linux).
- Alpine/musl is NOT supported by the CLI (no binary). Use a glibc image in CI.
Windows
- Python and the SDK work natively (
py -3.13 -m venv .venv,.venv\Scripts\Activate.ps1). - novaos-cli has NO native Windows binary: scaffold/publish from WSL 2 (
wsl --install -d Ubuntuin admin PowerShell, reboot) or a Mac/Linux machine. WSL is a candidate, not certified: confirm Docker and the sign-in callback work. - Docker Desktop with the WSL 2 backend:
winget install -e --id Docker.DockerDesktop.
Project virtual environment
python3 -m venv .venv
.venv/bin/python -m pip --isolated install --index-url https://pypi.org/simple/ "novaos-agent-sdk[llm]==2.1.0" fastapi==0.115.12 "uvicorn[standard]==0.34.2" pydantic==2.11.1
.venv/bin/python -c 'import importlib.metadata as m; from novaos_client_sdk import AgentBuilder, Client; print(m.version("novaos-agent-sdk"))'
.venv/bin/python -m pip check
Tool: novaos_python_env does all of this.
Install pitfalls (seen in real projects)
- Package name
novaos-agent-sdk, import namenovaos_client_sdk.import novaos_agent_sdkfails. - Never install the old vendored
novaos-client-sdk(0.12/0.14, ACP) next to 2.x: same import name, A2A imports break. - The
initscaffold README mentions TestPyPI andpip install --no-deps: stale. Use public PyPI;--no-depsdropsopenai(needed byLLMClient, extra[llm]). - SDK 2.x no longer brings uvicorn: pin
uvicorn[standard]yourself. - npm
novaos-cliis a launcher that downloads a platform binary from GitHub releases. If postinstall was skipped (pnpm, bun,--ignore-scripts) it downloads on first run; behind rate limits setNOVAOS_CLI_GITHUB_TOKEN; re-runnode "$(npm root -g)/novaos-cli/install.js". - GUI apps (Claude Desktop, Codex app) start MCP servers with a minimal PATH; this server adds Homebrew, bun, npm, ~/.local/bin and Docker paths automatically.
- Publish needs Docker running, not just installed (
docker infomust succeed). novaos-cli initdefaults to--lang typescript, whose SDK (@novaos/agent-sdk) is not on npm: always pass--lang python(or usenovaos_agent_create).