Skip to main content
Operator OS was designed from the ground up for constrained environments. Its Go runtime, CGO-free build, and single-binary distribution make it uniquely suited to edge hardware that cannot run typical Node.js or Python agent frameworks.

<10 MB RAM

99% smaller memory footprint than equivalent Python or Node.js agents.

<1s boot

Cold starts in under one second, even on single-core 0.6 GHz processors.

Single binary

No runtime dependencies, no package manager, no interpreter — copy and run.

​
Supported architectures

Precompiled binaries are published for every release via GoReleaser:
ArchitectureGOARCHExample hardware
x86_64amd64Standard servers, NUCs, x86 SBCs
ARM64arm64Raspberry Pi 3/4/5, Raspberry Pi Zero 2 W (64-bit), NVIDIA Jetson
ARMv7arm (GOARM=7)Raspberry Pi Zero 2 W (32-bit), older Pi models
ARMv6arm (GOARM=6)Raspberry Pi Zero (original)
RISC-V 64riscv64VisionFive 2, Milk-V Mars, Lichee Pi 4A
LoongArch64loong64Loongson 3A5000/3A6000 boards
Download the appropriate archive from the Releases page. Archives follow the naming convention operator_Linux_<arch>.tar.gz.

​
Cross-compilation

Operator OS uses CGO_ENABLED=0, which means you can cross-compile for any target from any host with Go 1.25+ installed. No toolchain, no sysroot. 
# For Raspberry Pi 3, 4, 5 and Zero 2 W (64-bit OS)
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build \
  -tags stdjson \
  -ldflags "-s -w" \
  -o build/operator-linux-arm64 \
  ./cmd/operator
Or use the Makefile shortcut:
make build-linux-arm64

​
Raspberry Pi setup

1

Transfer the binary

From your build machine:
scp build/operator-linux-arm64 [email protected]:/usr/local/bin/operator
Or download directly on the Pi:
curl -L https://github.com/avrilonline/Operator-OS/releases/latest/download/operator_Linux_arm64.tar.gz \
  | tar -xz -C /usr/local/bin operator
chmod +x /usr/local/bin/operator
2

Initialize the workspace

operator onboard
This creates ~/.operator/config.json and ~/.operator/workspace/.
3

Configure API keys

nano ~/.operator/config.json
Add at minimum a model_list entry and set agents.defaults.model. See Configuration overview for the full schema.
4

Run the gateway

operator gateway

​
RISC-V setup

1

Transfer the binary to the board

scp build/operator-linux-riscv64 [email protected]:/usr/local/bin/operator
chmod +x /usr/local/bin/operator
Boards confirmed working: StarFive VisionFive 2, Milk-V Mars, Sipeed Lichee Pi 4A.
2

Initialize the workspace

operator onboard
3

Configure and start

nano ~/.operator/config.json
operator gateway

​
Hardware interface access

Operator OS agents can interact with edge peripherals through the exec tool, which lets the agent run shell commands within its workspace sandbox.

​
I2C

Read a sensor register over I2C using standard Linux userspace tools: 
# List I2C buses
i2cdetect -l

# Scan bus 1 for devices
i2cdetect -y 1

# Read a register (e.g., BME280 chip ID at 0x60, register 0xD0)
i2cget -y 1 0x76 0xD0
Grant the agent access to I2C devices by adding the operator user to the i2c group: 
sudo usermod -aG i2c operator

​
SPI

SPI devices are accessible via /dev/spidev*. Enable SPI on Raspberry Pi by adding dtparam=spi=on to /boot/config.txt and rebooting. The spi-tools package provides spi-config and spi-pipe for testing.
You can instruct the agent to periodically poll sensors using the built-in cron tool and store readings in the workspace. This enables autonomous environmental monitoring without any additional application code.

​
Resource requirements

ResourceMinimumTypical (one channel)Notes
RAM4 MB6–10 MBGrows slightly with active session memory
Storage5 MB20–50 MBBinary + workspace + memory DB
CPUSingle-core 600 MHzAnyMost time is spent waiting on LLM API I/O
NetworkAnyAnyRequired for LLM API calls
OSLinux kernel 4.4+Linux kernel 5.x+Any libc-free userspace works; Alpine recommended

​
Auto-start with systemd

Running the gateway as a systemd service ensures it starts on boot and restarts automatically on failure.
1

Create the service file

Create /etc/systemd/system/operator.service:
[Unit]
Description=Operator OS Gateway
Documentation=https://operator.onl/docs
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=operator
Group=operator
ExecStart=/usr/local/bin/operator gateway
Restart=on-failure
RestartSec=5s

# Resource limits (optional — conservative defaults for edge boards)
MemoryMax=64M
CPUQuota=50%

# Working directory (operator reads config from $HOME/.operator)
WorkingDirectory=/home/operator

# Environment
Environment=TZ=UTC

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/home/operator/.operator

[Install]
WantedBy=multi-user.target
2

Create the operator user (if not already present)

sudo useradd -r -m -s /bin/false operator
3

Initialize the workspace as the operator user

sudo -u operator /usr/local/bin/operator onboard
sudo -u operator nano /home/operator/.operator/config.json
4

Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable operator.service
sudo systemctl start operator.service
5

Check status

sudo systemctl status operator.service
sudo journalctl -u operator.service -f
On systems without systemd (e.g., Alpine Linux with OpenRC), use a similar /etc/init.d/operator script or run the gateway under supervise / s6-svscan. The binary has no dependencies on systemd itself.

Build docs developers (and LLMs) love

Get started for freeTalk to us