Quickstart

Get your first VM with a deployed devcontainer running in about five minutes.

1. Install the CLI

# macOS
brew tap hyperengineering/tap
brew install swarm

# Debian/Ubuntu (client + server from the same apt repo)
curl -fsSL https://apt.fury.io/neuralmux/gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/neuralmux-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/neuralmux-keyring.gpg] https://apt.fury.io/neuralmux/ * *" | sudo tee /etc/apt/sources.list.d/neuralmux.list
sudo apt update
sudo apt install swarm

Or build from source — see Installation.

2. Start the server

The quickest path is Docker Compose:

git clone https://github.com/hyperengineering/swarm && cd swarm
cd packaging/docker
cp ../swarm-server.json.example swarm-server.json

Edit swarm-server.json: set your UpCloud credentials (see Server setup — you need either provider_token_cmd or UPCLOUD_TOKEN in the environment), then:

docker compose up -d

The server is now listening on https://localhost:8800. Its first start prints a one-time enrollment token to the logs:

docker compose logs swarm-server | grep -A2 "enrollment token"

3. Enroll this machine

swarm config set server https://localhost:8800
swarm login --token <token-from-the-logs>

swarm login generates a client keypair, exchanges it for a CA-signed certificate, and stores it in ~/.swarm. Every command after this authenticates automatically.

4. Save your VM defaults

swarm config set zone fi-hel1
swarm config set plan 1xCPU-1GB
swarm config set template 01000000-0000-4000-8000-000030200364

List what’s available with swarm vm zones, swarm vm plans, and swarm vm templates — the values above are examples.

5. Create a VM

swarm vm create --name my-server

The server provisions the VM with the cloud provider and registers it. First deploy to a VM automatically bootstraps it (Docker, Node.js, devcontainer CLI, swarm-agent) — you don’t need to do anything extra.

6. Deploy a devcontainer

swarm container deploy --repo https://github.com/example/project --alias dev

Watch it come up:

swarm container info dev
# status: running

7. Tear down

swarm container rm dev
swarm vm destroy my-server

That’s the whole lifecycle: create, bootstrap, deploy, tear down.

Next steps

• VM management — plans, zones, disk sizes, private networks
• Containers — env vars, secrets, batch deploys
• Security model — how enrollment, certificates, and revocation work