Linux

Prerequisites

Docker Engine with the Compose v2 plugin. Nothing else — VectorStep ships as container images, so there is no Python toolchain to set up and no source to check out. If docker compose version prints a version, you’re ready.

No Docker on this host?

See Standalone (no Docker) below — a native Linux install with no Docker, no Python, and no source, running under systemd.

Install

export ANTHROPIC_API_KEY=sk-ant-...
curl -sSL https://raw.githubusercontent.com/bantex01/VectorStep-Dist/main/install.sh | bash

This pulls the published images, starts VectorStep and the Gateway, reads the Gateway’s invoke token and wires it into VectorStep, prints the Gateway’s separate admin token (for authoring agents — see Gateway authentication), and seeds sample pipelines, steps, and agents. Everything lands in ~/.vectorstep/:

~/.vectorstep/
├── docker-compose.yaml     # managed by the installer, refreshed on re-run
├── .env                    # your keys, ports, image tag — never overwritten
├── config/
│   ├── vectorstep.yaml     # service config — yours to edit
│   └── gateway.yaml        # gateway config — yours to edit
├── pipelines/              # authored on the host, mounted into the container
├── steps/
└── agents/

Re-run the installer any time to upgrade — it refreshes the compose file and pulls new images while leaving .env and everything under config/, pipelines/, steps/, and agents/ exactly as you left them.

Add --service-only if the Gateway runs elsewhere or you drive VectorStep with OpenClaw. Add --postgres for PostgreSQL instead of the SQLite default — see Deployment.

Day-to-day

cd ~/.vectorstep
docker compose ps
docker compose logs -f vectorstep
docker compose up -d          # apply a config change
docker compose down           # stop, keeping data

Surviving a reboot

The compose services are declared restart: unless-stopped, so Docker brings them back after a reboot on its own, provided the Docker daemon itself is enabled:

sudo systemctl enable docker

That is enough for most installs. If you’d rather have systemd own the stack explicitly — so systemctl status vectorstep is meaningful and the unit can be ordered against other services — drop this in at /etc/systemd/system/vectorstep.service:

[Unit]
Description=VectorStep
Requires=docker.service
After=docker.service network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=vectorstep
WorkingDirectory=/home/vectorstep/.vectorstep
ExecStart=/usr/bin/docker compose --profile gateway up -d
ExecStop=/usr/bin/docker compose --profile gateway down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Then sudo systemctl enable --now vectorstep. Set User= and WorkingDirectory= to whichever account ran the installer, and make sure that account is in the docker group.

Standalone (no Docker)

For a host with no Docker, no Python, and no source — a plain VM, or an environment where containers aren’t an option — --native installs standalone Linux binaries under systemd instead of containers:

export ANTHROPIC_API_KEY=sk-ant-...
curl -sSL https://raw.githubusercontent.com/bantex01/VectorStep-Dist/main/install.sh | sudo bash -s -- --native

Must run as root. The binaries are built inside a pinned python:3.11-slim-bullseye container (glibc 2.31), so they run on Ubuntu 22.04 LTS and newer, and on Debian 11+ — a broader floor than a plain ubuntu-latest-built binary would give, since glibc is forward-compatible but not backward-compatible.

Everything lands in a fixed FHS layout rather than ~/.vectorstep/ — --dir doesn’t apply here:

/opt/vectorstep/{vectorstep,vectorstep-gateway}/bin/   # the binaries
/etc/vectorstep/{vectorstep,vectorstep-gateway}/       # config.yaml, env (secrets, token)
/var/lib/vectorstep/vectorstep/{db,pipelines,steps,...}
/var/lib/vectorstep/vectorstep-gateway/{identity,agents}
/var/log/vectorstep/{vectorstep,vectorstep-gateway}/

Both services run as systemd units (vectorstep, vectorstep-gateway), already enabled, so they come back after a reboot with no extra step — unlike the Docker path above, there’s no separate wrapper unit to write.

systemctl status vectorstep vectorstep-gateway
journalctl -u vectorstep -f

Prerequisites beyond the binary itself: Node.js and/or uv/uvx, but only if you configure npx- or uvx-based MCP servers — the binary doesn’t bundle a JavaScript or separate Python runtime, and a bare install with no MCP servers configured needs neither. This isn’t checked at install time: if your config needs one and it’s missing, the Gateway starts fine but logs an error for that specific MCP server when it fails to spawn — every other server and agent keeps working.

Architecture: both x86_64 (amd64) and aarch64 (arm64) are published from v0.1.1 onward. amd64 is built by CI on every release; arm64 is built and published by hand, separately, so it can occasionally lag a fresh release by a short window. If a given version genuinely has no arm64 asset yet, the installer detects it, says so plainly, and points at the container install instead of guessing — use Docker above, which publishes multi-arch images.

Upgrade: re-run the same command — binaries are replaced, config and state (including the Gateway’s tokens) are left alone.

Uninstall:

# Removes the units and /opt, /etc. Keeps the database and authored
# pipelines/agents under /var/lib, and prints where they are.
curl -sSL .../install.sh | sudo bash -s -- --native --uninstall

# Also removes /var/lib, /var/log, and the vectorstep user — irreversible,
# hence the required --yes (there's no interactive prompt under curl | bash).
curl -sSL .../install.sh | sudo bash -s -- --native --uninstall --purge --yes

Production

For anything beyond a single host, see Kubernetes — plus the two constraints (single replica, in-process migrations) worth knowing before you apply the manifests. Database and config decisions are covered in Deployment.