Swarm

What is Swarm?

Swarm is a client/server tool that provisions virtual machines and deploys devcontainers on them. It manages the full lifecycle: VM creation, bootstrapping (Docker, Node.js, devcontainer CLI, swarm-agent), container deployment, and teardown.

One CLI — swarm talks to a single control-plane server. All cloud credentials, SSH keys, and agent binaries live server-side.
Devcontainers first — deploy a repo and get a working container environment, the same one you use in VS Code, running on your own VM.
Secure by default — the API is protected by mutual TLS with one-time enrollment, serial-based revocation, and CA-signed client certificates.
Batch and scale — deploy a repo across many VMs with a single command and automatic placement.

Architecture

CLI (swarm) --HTTPS (mTLS)--> Server (swarm-server) --SSH--> Agent (swarm-agent)
                                                              |
                                                         Docker containers

Three components:

Component	What it does
`swarm`	CLI client. Sends HTTPS requests to the server; handles interactive operations directly via SSH.
`swarm-server`	Control-plane daemon. Manages the registry, talks to cloud providers (UpCloud), bootstraps VMs, and communicates with agents over SSH.
`swarm-agent`	Runs on each VM. Manages Docker containers via the devcontainer CLI and reports status back to the server.

The CLI only needs the server URL and a one-time enrollment to operate.

Install

# CLI on macOS
brew tap hyperengineering/tap
brew install swarm

# Server on Debian/Ubuntu
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-server

Docker images are published to ghcr.io/hyperengineering/swarm-server.

Status

Swarm is in beta (v0.8). The API and CLI are stable in practice but not frozen. See Known limitations for the current boundaries.

Built by NeuralMux. Licensed under MIT.

Resources

Quickstart

Provision your first VM and deploy a devcontainer in minutes.

API reference

Every swarm-server endpoint, parameter, and error code.

CLI setup

Install and configure the swarm CLI on macOS and Linux.

FAQ

Answers to common questions about Swarm.

Provision VMs. Deploy devcontainers.