NovaOS MCP
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

  1. 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).
  2. brew install python@3.13 node git
  3. brew install --cask docker, open Docker Desktop once, wait for "Engine running".
  4. brew install orbitronai-repo/novaos/novaos-cli (or npm install -g novaos-cli).
  5. Check: novaos-cli version (NOT --version: that flag errors; -V works).

Linux (glibc: Ubuntu/Debian)

  1. sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip git
  2. Node 20: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs
  3. Docker: curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker $USER (log out/in).
  4. 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 Ubuntu in 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 name novaos_client_sdk. import novaos_agent_sdk fails.
  • Never install the old vendored novaos-client-sdk (0.12/0.14, ACP) next to 2.x: same import name, A2A imports break.
  • The init scaffold README mentions TestPyPI and pip install --no-deps: stale. Use public PyPI; --no-deps drops openai (needed by LLMClient, extra [llm]).
  • SDK 2.x no longer brings uvicorn: pin uvicorn[standard] yourself.
  • npm novaos-cli is 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 set NOVAOS_CLI_GITHUB_TOKEN; re-run node "$(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 info must succeed).
  • novaos-cli init defaults to --lang typescript, whose SDK (@novaos/agent-sdk) is not on npm: always pass --lang python (or use novaos_agent_create).