Fleet Deployment

Deploy to multiple servers via SSH. No control plane, no agent, no Kubernetes. Just SSH and niso on each host.

Overview#

Fleet deployment lets you deploy packages across multiple servers using SSH. niso connects to each host, pushes the package, and activates it — with rolling, canary, or all-at-once strategies.

There is no central server, no agent to install, no control plane. Each host just needs niso installed and SSH access.

Fleet configuration#

fleet.toml

[fleet]name = "production"[[host]]name = "web-1"address = "ssh://deploy@10.0.1.10"labels = { role = "web", region = "eu" }[[host]]name = "web-2"address = "ssh://deploy@10.0.1.11"labels = { role = "web", region = "eu" }[[host]]name = "worker-1"address = "ssh://deploy@10.0.1.20"labels = { role = "worker", region = "eu" }[registry]url = "https://registry.example.com"[deploy]strategy = "rolling"health_timeout = "60s"

Deploy commands#

bash

# Deploy to all hosts$ niso fleet deploy my-api 1.2.0  [web-1]    ✓ pulled → activated → healthy (2s)  [web-2]    ✓ pulled → activated → healthy (3s)  [worker-1] ✓ pulled → activated → healthy (1s)# Deploy to hosts matching a label$ niso fleet deploy my-api 1.2.0 --hosts "role=web"# Deploy with canary strategy (25% first, then rest)$ niso fleet deploy my-api 1.2.0 --strategy canary# Fleet status$ niso fleet status  HOST       PACKAGE    VERSION  STATUS   HEALTH  web-1      my-api     1.2.0    active   healthy  web-2      my-api     1.2.0    active   healthy  worker-1   my-api     1.2.0    active   healthy# Show version per host$ niso fleet versions my-api# Fleet-wide rollback$ niso fleet rollback my-api  [web-1]    ✓ rolled back to 1.1.0  [web-2]    ✓ rolled back to 1.1.0  [worker-1] ✓ rolled back to 1.1.0

Deployment strategies#

Strategy	Behavior
`rolling`	One host at a time. Waits for health check before proceeding. Rolls back the failing host on error.
`canary`	Deploys to a subset first (25%). Waits for health check. If healthy, deploys to remaining hosts.
`all-at-once`	Deploys to all hosts in parallel. Fastest, but riskiest. Use for non-critical services.

Stack deployment#

Deploy an entire stack across the fleet:

bash

# Deploy stack to all hosts$ niso fleet stack up --file stack.toml# Deploy stack to specific hosts$ niso fleet stack up --file stack.toml --hosts "role=web"# Show diff across fleet$ niso fleet stack diff --file stack.toml

Host contexts#

Manage individual remote hosts without a fleet file:

bash

# Create a context$ niso context create staging --host ssh://deploy@staging.example.com# Switch to it$ niso context use staging# All commands now run on the remote host$ niso status$ niso logs my-api# Or use --host for one-off commands$ niso --host ssh://deploy@staging.example.com status

Failure handling#

Fleet deployments use exit codes to indicate the result:

0 — all hosts succeeded
1 — partial failure (some hosts failed, others succeeded)
2 — total failure (all hosts failed)

On failure with the rolling strategy, the failing host is automatically rolled back. Other hosts are left on the new version.