Quickstart

From zero to a private, shareable app URL in about five minutes.

What do I need before installing Smallcloud?

• A Linux server with Docker installed.
• caddy-docker-proxy as the reverse proxy, discovering routes from container labels (Coolify installs ship this by default).
• A domain — or not: smallcloud domain claim yourname gets you a free yourname.onsmallcloud.com pointed at your server, no DNS knowledge needed. Bringing your own domain = one wildcard record (*.example.com, any provider); TLS is automatic via Let's Encrypt either way.
• Node.js 22 and pnpm (corepack enable pnpm).

Install

One command on your server:

npm install -g @onsmallcloud/smallcloud

That installs the smallcloud CLI (and smallcloud-mcp for AI agents). This step sets up the Smallcloud platform on your server, once. Your own apps live anywhere else — you'll point smallcloud deploy at them in a moment.

Permission error (EACCES)? You're installing into a root-owned system Node. Don't reach for sudo — use a user-owned Node 22 via nvm (nvm install 22), which also satisfies Smallcloud's Node 22 requirement. System Node 20 fails at runtime even with sudo.

Then give your server a domain — the zero-setup way:

smallcloud domain claim yourname   # free yourname.onsmallcloud.com, config written for you

Or bring your own: set it once in ~/.smallcloud/config.json as { "baseDomain": "example.com" } (you can switch from a claimed subdomain to your own domain anytime — it's just this one config line).

Deploy your first app

smallcloud new hello --template kv   # or: static, node
cd hello
smallcloud deploy --email <your-email>

The first deploy boots Smallcloud's own services automatically. You get back two lines: the app's URL (private — visitors hit a sign-in wall) and a single-use sign-in link. Click the link, get a 30-day session, see your app.

Check on it

smallcloud list          # every app, status, URL
smallcloud logs hello    # recent output
smallcloud doctor        # verify + heal the installation

Where to next?

Deploy something real with the Node.js app guide, give a teammate access with sharing & roles, or let your AI agent do all of this via MCP.