Skip to content
Swarm

FAQ

The proxy returns 502 target port unreachable

Section titled “The proxy returns 502 target port unreachable”

The single most common foot-gun: your service is bound to 127.0.0.1:8900 inside the container instead of 0.0.0.0:8900. The agent dials the container’s bridge IP, which can’t reach loopback. Rebind to 0.0.0.0. See the proxy guide.

How do I open a shell into a container?

Section titled “How do I open a shell into a container?”

The CLI doesn’t have a shell command in this release. From your workstation:

Terminal window
ssh root@<vm-ip> -- docker exec -it <docker-id> bash

<docker-id> is the CONTAINER ID from swarm container list.

How do I forward a port to a container?

Section titled “How do I forward a port to a container?”

Use SSH local port forwarding:

Terminal window
ssh -L 3000:<container-bridge-ip>:3000 root@<vm-ip>

For HTTP services, the container HTTP proxy is usually simpler — no SSH needed on the caller side.

My VM is unreachable

Section titled “My VM is unreachable”

Check the server side: swarm vm info <name> shows live provider status. If the VM is up but the agent can’t be reached, re-bootstrap:

Terminal window
swarm vm bootstrap <name>

My container deploy fails with a git error

Section titled “My container deploy fails with a git error”
  • For private repos, register a credential for the repo’s host: swarm git-credential add github.com (token from stdin). Use a read-only, repo-scoped token.
  • The credential must match the repo URL’s host exactly (github.com, not www.github.com).

How do I rotate a secret?

Section titled “How do I rotate a secret?”

swarm secret set <name> is an upsert — run it again with the new value. Containers pick up the new value at their next start; running containers keep the env they started with.

Why is my secret name rejected?

Section titled “Why is my secret name rejected?”

Secret names are injected verbatim as environment variable names, so they must be valid env var keys: [A-Za-z_][A-Za-z0-9_]*. Name it exactly what the container should see (e.g. NMUX_GEMFURY_TOKEN, not nmux-token).

How do I get a bigger boot disk?

Section titled “How do I get a bigger boot disk?”

Disk size applies at creation: swarm vm create --disk-size 100 (10–2048 GB). There is no live resize — provision a new VM and redeploy.

Batch deploys: why are my aliases dev-1, dev-2…?

Section titled “Batch deploys: why are my aliases dev-1, dev-2…?”

With --count N (N > 1), aliases get numeric suffixes. --count 1 uses the alias verbatim. Aliases must match [A-Za-z0-9][A-Za-z0-9_-]{0,62}.

Can I use my own TLS certificate for the server?

Section titled “Can I use my own TLS certificate for the server?”

Yes — set tls_cert/tls_key in swarm-server.json. Otherwise the server uses a CA-signed self-signed cert; set tls_sans so clients can reach the server by its public name.

Does Swarm work with providers other than UpCloud?

Section titled “Does Swarm work with providers other than UpCloud?”

Not yet. The provider layer is abstracted server-side, but UpCloud is the only implemented provider.

How do users get access to my server?

Section titled “How do users get access to my server?”

Mint a one-time enrollment token with swarm server token and hand it to them. They run swarm login --token <token> once. Revoke access at any time with swarm user revoke <serial> (see the security model).

Does the proxy support WebSockets?

Section titled “Does the proxy support WebSockets?”

No, not in v1. Upgrade headers are stripped; the handshake cannot complete.

Where are secrets and credentials stored?

Section titled “Where are secrets and credentials stored?”

Server-side, in root-only (0600) files next to the registry (secrets.json, git-credentials.json, tokens.json). Values are never returned by the API — only names/has_value flags.

What do the container statuses mean?

Section titled “What do the container statuses mean?”

deploying (in progress), running (Docker container alive), failed (deployment failed), dead (stopped/removed), unreachable (agent couldn’t be reached).