From an empty VPS
to a healthy app.

QUICK START

Three boundaries, one deployment.

Activate the CLI once, let the repository declare the app, and Small schedules it onto managed capacity by default.

RUNTIME

Connect a customer-owned VPS.

This is optional. Leave target.server unset to use Small Cloud without connecting a VPS.

1. Open Dashboard → Runtimes → Connect your VPS.
2. Copy the signed installation block.
3. SSH to a fresh supported VPS as a user with sudo access and run the generated installation block.
4. The installer displays a short setup code. Enter it with a stable server name and region in the dashboard, then approve the connection.
5. Wait for the installer and dashboard to report both heartbeat and managed ingress ready.

The installer reuses Docker Engine 24 or newer when healthy. Otherwise it installs Docker from its official signed APT repository. Small Node, its private Node.js runtime, and FRPC are pinned inside an Ed25519-verified release.

AGENT ACCESS

Use the same contract from any harness.

Start with small login. It accepts the one-time invite in the terminal, opens browser signup, and automatically delivers a scoped credential back to the waiting CLI. Dashboard → Agent setup then registers the MCP server and portable skill. The stdio MCP server exposes validation, deployment, status, logs, secrets, domain, and rollback operations.

curl --proto '=https' --tlsv1.2 -fsSL https://smallcloud.sh/cli/install.sh | sh
small login
codex mcp add small -- small mcp
claude mcp add --transport stdio --scope user small -- small mcp
curl --proto '=https' --tlsv1.2 -fsSL https://smallcloud.sh/skills/deploy-with-small/install.sh | sh

DEPLOYMENT CONTRACT

Keep intent in small.yaml.

An application must listen on 0.0.0.0 at the declared service port. Health endpoints should be fast and unauthenticated. Pin production images to a version or digest; Small records and runs the resolved immutable digest.

version: 1
name: hello-small
source:
  type: image
  image: nginx:alpine
service:
  port: 80
  healthcheck:
    path: /
resources:
  memoryMb: 128
  cpus: 0.25
storage: []
access:
  mode: public
env: {}
secrets: []
target:
  server: production-vps-1

OPERATIONS

Observe, replace, and recover.

Deployments progress through bounded milestones: source fetch, image pull or build, container start, health, ingress, and activation. A new release becomes active only after health and routing succeed.

small deploy --server production-vps-1
small status
small logs hello-small
small rollback <deployment-id>
small stop hello-small --yes

Replacement cleanup is deterministic. Rollback uses the historical image digest rather than resolving an old mutable tag again.

SECRETS

Declare names, supply values out of band.

List required names under secrets, then read values from the environment of the trusted CLI or MCP process. Secret values are encrypted and are never returned by list operations.

export DATABASE_URL='postgres://…'
small secrets set --app hello-small --from-env DATABASE_URL DATABASE_URL
unset DATABASE_URL
small secrets list --app hello-small

REQUEST PATH

Know where application traffic goes.

In the current managed-relay mode, public application requests cross Small's edge and relay, but never the dashboard HTTP process. Small does not receive SSH access or a remote Docker socket. The constrained node leases only commands assigned to its runtime identity.

TROUBLESHOOTING

Start with evidence, then repair.

sudo small-node-installer check
sudo systemctl status small-node --no-pager
sudo journalctl -u small-node -n 200 --no-pager
sudo small-node-installer repair

PRIVATE ALPHA

Current limits are part of the contract.

• Managed relay is the supported customer-VPS ingress mode today. Direct-edge Caddy mode is roadmap work.
• Small does not purchase or provision a VPS for you yet.
• Persistent volumes remain single-node data. Back up stateful application data independently.
• Small is not Kubernetes, a remote shell, or a general server administration control plane.