Installing Matrix OS
Get Matrix OS up and running on your system in minutes. Follow our step-by-step guide for a smooth installation experience.
System Requirements
Hardware Requirements
- CPU: 64-bit processor, 2 cores minimum
- RAM: 4GB minimum (8GB recommended)
- Storage: 1GB free space
- Network: Stable internet connection
Software Requirements
- OS: Linux, macOS, or Windows 10/11
- A release archive needs nothing else - both binaries are statically linked
- To build from source: Go 1.24.2 or newer, and buf
- Git, to clone the repository
Installation
Build from source
The supported path today, and the one the release workflow itself runs. You need Go (the version pinned in services/core/go.mod) and buf, which generates the Protocol Buffers stubs the CLI imports. There is no package-manager install and no installer script.
git clone https://github.com/savagemanage/matrix-os.git
cd matrix-os
# Generate the Protocol Buffers stubs the CLI imports.
make proto
cd services/core
go build -o matrix ./cmd/matrix
go build -o matrixd ./cmd/matrixdThis produces two binaries: matrix, the CLI, and matrixd, the node. Put them somewhere on your PATH if you want them available everywhere.
Prebuilt binaries
Tagged releases publish archives for Linux, macOS and Windows on x64 and arm64, each containing both binaries, alongside a SHA256SUMS file generated over those archives. Unix archives are .tar.gz; Windows is a .zip. The download page reads the release list directly, so it shows only what exists - if it offers nothing, nothing has been published yet. Git Bash users: do not feed uname -s into the URL. That string is MINGW64_NT-..., not windows.
TAG=$(curl -fsSL https://api.github.com/repos/savagemanage/matrix-os/releases/latest \
| grep -m1 '"tag_name"' | cut -d'"' -f4)
UNAME=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
case "$UNAME" in
linux*) OS=linux; EXT=tar.gz ;;
darwin*) OS=darwin; EXT=tar.gz ;;
mingw*|msys*|cygwin*) OS=windows; EXT=zip ;;
*) echo "unsupported uname: $UNAME (need linux, darwin, or Git Bash on Windows)"; exit 1 ;;
esac
curl -fsSLO "https://github.com/savagemanage/matrix-os/releases/download/$TAG/matrix-os-$TAG-$OS-$ARCH.$EXT"
curl -fsSLO "https://github.com/savagemanage/matrix-os/releases/download/$TAG/SHA256SUMS"
sha256sum -c SHA256SUMS --ignore-missing
if [ "$EXT" = zip ]; then unzip -o "matrix-os-$TAG-$OS-$ARCH.zip"; else tar xzf "matrix-os-$TAG-$OS-$ARCH.tar.gz"; fiPost-Installation Setup
Verify Installation
Both binaries report their version. A release prints its tag; a binary you built yourself prints dev, which is the honest answer for a build that did not come from a tag.
matrix --version # matrix version v0.1.0 (or "dev")
matrixd -version # matrixd v0.1.0 (or "dev")
matrix --help # the full command treeInitial Configuration
Configure your Matrix OS installation with the interactive setup wizard:
matrix-os setupNext Steps
Now that you have Matrix OS installed, you can:
- Follow our Quick Start Guide to create your first agent
- Learn about configuration options