Installation

Use this page to get a StacyVM server running before you follow the quickstart.

Prerequisites

Linux is recommended for runtime work. macOS is useful for SDK and docs development, but Docker provider behavior should be certified on Linux before public claims.
Docker is required for the default local provider path.
Go is required only when building from source.

See Prerequisites for the full local, SDK, and production checklist.

OS-Specific Setup

Use the Prerequisites OS setup before choosing an installation mode:

macOS: Docker Desktop plus Go for make serve.
Windows: WSL 2 with Ubuntu and Docker Desktop WSL integration.
Linux: Docker and Go from your distribution package manager.
Ubuntu: Docker Engine, Compose plugin, Go, Git, curl, and make.

For individual local development from a source checkout, use the one-command setup:

make dev

This checks the host, builds StacyVM, and starts the API server. You can also use the npm/npx bootstrapper:

npx stacyvm-setup@latest

That command can clone the repo, install Node package dependencies, download Go modules, build StacyVM, and start the server. It does not install Docker Desktop or Go for you.

Option 1: Release Binary

Use a signed GitHub release for production-like installs.

curl -L -o stacyvm.tar.gz \
  https://github.com/StacyOS/stacyvm/releases/latest/download/stacyvm_linux_amd64.tar.gz
tar -xzf stacyvm.tar.gz
sudo install -m 0755 stacyvm /usr/local/bin/stacyvm

Validate the release artifacts before you install them in production:

scripts/post-release-validate.sh v0.14.4

Replace v0.14.4 with the release tag you plan to deploy.

Option 2: Docker Compose

The repository includes a production-oriented Docker Compose starting point.

cd deploy
cp .env.example .env
docker compose up -d
docker compose logs -f stacyvm

Edit .env before exposing the service. Use strong API keys, exact CORS origins, and a persistent data directory.

Option 3: Source Checkout

Build from source when you are contributing to StacyVM itself.

git clone https://github.com/StacyOS/stacyvm.git
cd stacyvm
make dev

Configure Auth

For local experiments you can run without auth. For any shared host, enable auth and pass X-API-Key from clients.

auth:
  enabled: true
  api_key: "sk_live_REPLACE_ME"
server:
  cors_allowed_origins:
    - "https://your-app.example.com"

Verify The Host

Run config validation before a deploy:

stacyvm config lint --production --file deploy/stacyvm.production.yaml

Run live host diagnostics after the service is installed:

stacyvm doctor --production

Continue

Once the server responds, follow the quickstart. If setup fails, use the troubleshooting guide.

Get Started

Build With StacyVM

Operate

Production Readiness

Runtime And Conformance

Architecture

Release Notes

Prerequisites

OS-Specific Setup

Option 1: Release Binary

Option 2: Docker Compose

Option 3: Source Checkout

Configure Auth

Verify The Host

Continue

​Prerequisites

​OS-Specific Setup

​Option 1: Release Binary

​Option 2: Docker Compose

​Option 3: Source Checkout

​Configure Auth

​Verify The Host

​Continue

Prerequisites

OS-Specific Setup

Option 1: Release Binary

Option 2: Docker Compose

Option 3: Source Checkout

Configure Auth

Verify The Host

Continue