> For the complete documentation index, see [llms.txt](https://docs.simplephysx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.simplephysx.com/getting-started/installation-guide.md). # Installation Guide Install SPX with the ready native installer for your platform, then run SPX Setup to generate and start your local environment. The recommended installation path is to use the ready native installer for your operating system. The installer packages include the setup wizard and the SPX Tools launchers you need for day-to-day work. Quick path: 1. Make sure Docker is installed and running. 2. Download the installer for your platform from the signed-in download page. For RC testing use [staging Downloads](https://staging.simplephysx.com/account/downloads), channel **Development**. 3. Run the native installer. 4. On macOS, use the `SPX Setup` window opened automatically after installation. Open it from SPX Tools if it did not launch; avoid running a second wizard. 5. Let `SPX Setup` generate and start your local SPX environment. 6. Verify the UI and API on localhost. 7. Launch `SPX MCP Setup`, open the generated `SPX MCP Workspace` in Codex, Claude Code, or another MCP-capable client, and start a fresh session so the client loads the local MCP config. After setup, verify: * **UI**: `http://localhost:3000` * **API**: `http://localhost:8000` * **API docs**: `http://localhost:8000/docs` ## Reference repository: spx-examples Native installers are the recommended first path. For advanced bundle generation, installer profiles, pack definitions, runnable models, and MiL tests, use the public [spx-examples repository](https://github.com/HammerHeads-Engineers/spx-examples). ## Prerequisites * Docker must be installed and running before you start SPX. * Windows and macOS users should use Docker Desktop. * Linux users need Docker Engine with Docker Compose v2. * A valid SPX product key is required. * Native macOS and Windows packages provide Python 3.12, including MCP support. Portable/Linux setup uses the host Python: 3.9+ for the installer and 3.10+ for `SPX MCP Setup`. * Local ports `3000` and `8000` should be available. > Security: treat your `SPX_PRODUCT_KEY` as a secret. Do not commit it to git or share generated bundles that contain a real key. ## 1) Download the installer For the current public platform, download through [simplephysx.com/keys](https://simplephysx.com/keys). The new staging platform has separate [Downloads](https://staging.simplephysx.com/account/downloads) and [Product Keys](https://staging.simplephysx.com/account/product-keys) pages. Select **Development** to qualify a release candidate. Confirm the package version and compare its SHA-256 with the checksum on the download page. Use the package for your platform: * Windows: `spx-installer-.exe` * macOS: `spx-installer-macos-.pkg` * Linux/Unix: `spx-installer-.run` Use the file actually offered for the selected release. A portable `.tgz` contains the unpacked installer payload and shell launchers; it is not a `.tar` delivery wrapper containing a `.run`. If a Windows delivery `.zip` is offered, extract it before running its `.exe`. Open the macOS `.pkg` directly. ## 2) Run the native installer ### Windows Extract the Windows archive if needed, then run `spx-installer-.exe`. * Installs SPX Tools under the per-user SPX location. * Adds SPX Tools entries to Windows Apps / Start Menu. * If Python is missing, the installer can install the official Python 3.12 offline prerequisite. ### macOS Open `spx-installer-macos-.pkg`. * Installs SPX Tools into `/Applications/SPX Tools/`. * Uses the native macOS Installer experience, including the license step. * Installs the official universal Python 3.12 runtime and opens Setup automatically after installation for the signed-in user. * Installs launcher apps such as `SPX Setup.app`, `SPX Start.app`, `SPX MCP Setup.app`, `SPX Stop.app`, `SPX Cleanup.app`, and `SPX Uninstall.app`. ### Linux/Unix For a self-extracting `.run`, make it executable and run it: ```bash chmod +x spx-installer-.run ./spx-installer-.run ``` The `.run` package starts the same terminal setup flow used by SPX Setup. After setup, day-to-day work happens through the generated shell scripts such as `spx-start.sh` and `spx-stop.sh`. If Downloads offers a portable `.tgz`, use: ```bash tar -xzf spx-installer-.tgz cd spx-installer ./spx-install.sh ``` ## 3) Run SPX Setup Use the automatically opened Setup on macOS. If it is absent, launch `SPX Setup` once from the location below. Where to find it: * Windows: Start Menu / Windows Apps under `SPX Tools`. * macOS: `/Applications/SPX Tools/SPX Setup.app`. * Linux/Unix: the `.run` package launches the setup flow; generated scripts are used after setup. `SPX Setup` is the main environment wizard. It: * asks which packages or protocols you want, * asks for your SPX product key, * generates the local Docker Compose bundle, * writes helper scripts, * can start the stack immediately. If you accept the default package selection, setup uses the default protocol set (`Modbus + SCPI/ASCII` when available), keeps SPX UI enabled, and skips model installation. If you select a pack, decide explicitly whether to add models and starter instances. For a protocol-only first run, explicitly enable model installation. The UI initially has no instances; follow [First device in the UI](/getting-started.md#first-device-in-the-ui) to create one. Keep LAN exposure disabled for local checks. ## 4) Verify the local stack After `SPX Setup` starts the stack, or after running `SPX Start`, verify: 1. Open the UI at `http://localhost:3000`. 2. Check API health. macOS/Linux: ```bash curl -fsS http://localhost:8000/health ``` Windows PowerShell: ```powershell (Invoke-WebRequest http://localhost:8000/health).Content ``` 3. Open API docs at `http://localhost:8000/docs`. The expected health response includes `"status":"ok"`. Record the installer version and the SPX Server/UI image tags from the generated `docker-compose.generated.yml`. They have separate version series. The installer's `installer/compatibility.py` records the supported Server/UI pair; do not replace either image with an arbitrary newer tag during RC qualification. If Docker is unavailable, Setup explains whether the CLI, Engine or Compose is missing. Start or unpause Docker Desktop, wait for Engine to be running, and press Enter to retry. On macOS the tools search Docker Desktop's bundled CLI and the per-user Docker bin directory, so a manual PATH edit is not required. ## 5) Connect an LLM with SPX MCP SPX MCP is the recommended next step after the local stack is running. It lets MCP-capable LLM clients call the local SPX server through the packaged `spx-mcp` server, inspect models and instances, register catalog models, and make runtime changes through MCP tools. Launch `SPX MCP Setup`: * Windows: Start Menu / Windows Apps under `SPX Tools`. * macOS: `/Applications/SPX Tools/SPX MCP Setup.app`. * Linux/Unix or portable payload: run `spx-mcp-setup.sh` from the installer payload. The setup creates an `SPX MCP Workspace` with: * a local `.venv` for the MCP server, * `.codex/config.toml` pointing Codex at the local `spx-mcp` server, * `.mcp.json` pointing Claude Code at the same local `spx-mcp` server, * `CLAUDE.md` so Claude Code can follow `@AGENTS.md`, * `.spx/workspace_mode.toml` with the selected work mode, * `.spx-mcp-workspace.json` with workspace metadata. Choose `runtime_mcp` for normal post-install work with the local `spx-server`. Use `repo_dev` only when you want a full `spx-examples` checkout for durable repository changes, tests, docs, commits, or PRs. Packaged workspaces are read/write by default; use read-only mode only for inspection-only access. Existing `.codex/workspace_mode.toml` files are still read as a legacy fallback. After setup finishes, open the generated workspace in Codex, Claude Code, or another MCP-capable client and start a fresh session so the client reloads the local MCP configuration. Full walkthrough: [Connect an LLM with SPX MCP](/getting-started/connect-llm-with-spx-mcp.md). ## 6) Use SPX Tools After setup, use the installed SPX Tools instead of rerunning the installer. ### `SPX Setup` Generates or refreshes your local SPX environment. Use it when installing for the first time, changing packages, or regenerating the runtime bundle. ### `SPX Start` Starts the previously generated SPX stack. Use it for normal day-to-day startup after setup has already generated the environment. ### `SPX Stop` Stops the services carrying this installation's ownership ID, including KNX and other selected auxiliary services. Rollback snapshots and unrelated containers are excluded. Verify the selected services are stopped before starting again. ### `SPX Cleanup` On macOS, stops the managed stack and removes the generated/runtime directories. This deletes local configuration and disk snapshots in those directories. It does not uninstall SPX Tools or remove Docker images, volumes or unrelated containers. Export snapshots you want to keep before using Cleanup. ### `SPX MCP Setup` Creates or refreshes the SPX MCP workspace for local MCP access. Use it after the SPX stack is generated and reachable on `http://localhost:8000`. ### `SPX Uninstall` macOS has a dedicated `SPX Uninstall.app` in `/Applications/SPX Tools/`. It stops the local stack, removes SPX support files and launcher apps, and forgets the SPX package receipt. The dialog lets you choose whether to remove the managed MCP workspace. Back up snapshots first. Docker Desktop and the shared Python framework are not removed by this SPX operation. On Windows, uninstall SPX Tools through the standard Windows Apps / installed app management flow. On Linux/Unix, remove the generated environment and package files according to the distribution method you used. ## 7) What SPX Setup creates The generated runtime environment contains: * `docker-compose.generated.yml` * `.env` * `bundle.json` * start/stop scripts for Bash, zsh, PowerShell, and desktop launchers * selected assets, extensions, and model library files Default generated locations: * Windows: `%LocalAppData%\SPX\generated` * macOS: `~/Library/Application Support/SPX/generated` * Linux/Unix: `~/.local/share/spx/generated` ## Advanced fallback Use portable archives or manual Docker Compose only when you intentionally need an advanced fallback flow, debugging payload, or server-only setup. * Portable installer and packs: [Installer and packs](/advanced-setup/installer-and-packs.md) * Server-only Compose: [Advanced: Manual Docker Compose](/getting-started/manual-docker-compose.md) * Troubleshooting: [Common Issues and Solutions](/operations-and-support/troubleshooting-and-support/common-issues-and-solutions.md) ## Next steps * Connect an MCP-capable LLM client: [Connect an LLM with SPX MCP](/getting-started/connect-llm-with-spx-mcp.md) * Smart Building Pack walkthrough: [Smart Building Pack: First Run Walkthrough](/getting-started/first-run-smart-building-pack.md) * Build your own simulation: [Build Your First Simulation](/getting-started/build-your-first-simulation.md) * Troubleshooting runbook: [Common Issues and Solutions](/operations-and-support/troubleshooting-and-support/common-issues-and-solutions.md) ## Next steps on simplephysx.com Explore where SPX fits in testing and commissioning workflows: * [Embedded Software Testing](https://www.simplephysx.com/embedded-software-testing) * [Virtual Commissioning](https://www.simplephysx.com/virtual-commissioning)