Get started: Client

Connect a developer machine to a StackPaaS daemon someone else operates.

This guide is for engineers whose team already has a stackcubed daemon running somewhere. You'll install the CLI, point it at the daemon, and deploy your first app. If you need to set the daemon up yourself, see Get started: Server first.

Requirements

Install

Homebrew

brew tap stackcube/tap
brew install stackcube

You only need stackcube as a client — leave stackcubed uninstalled.

Configure the CLI

Tell the CLI where the daemon lives and which key to authenticate with:

stackcube init \
  --server paas.example.com:443 \
  --tls \
  --identity ~/.ssh/id_ed25519

This writes ~/.stackcube/client.yml — the file the CLI reads on every subsequent invocation.

The daemon's gRPC server runs on port 9090, but it sits behind a bundled Caddy proxy that binds host ports 80 and 443 and handles TLS for you. Connect to :443 with --tls as a remote engineer; :9090 direct (no TLS) only works on the same host as the daemon.

Note: StackPaaS authenticates with SSH keys, not passwords or OAuth. The signature happens locally — your private key never leaves the machine.

Smoke test

Confirm the daemon is reachable and your key is authorized:

stackcube list

An empty table (or a table of apps if some are deployed) means you're connected. An auth error means your key isn't registered yet — ask an admin to run stackcube keys add on your behalf.

Get the daemon's deploy key

The daemon needs read access to your app's git remote so it can fetch the commit you push. Grab its public deploy key and add it as a deploy key on your git host (GitHub, GitLab, etc.):

stackcube deploy-key

The same key serves every app on this daemon — you only need to add it once per git remote.

Deploy your first app

1. Scaffold a compatible compose file

From inside your app's git repo (or a fresh project directory):

stackcube scaffold

This generates docker-compose.yml + .env following the app contract. Add a Dockerfile next to them. If your repo already has a compose file, run stackcube lint to check it.

2. Register the app

stackcube create my-api --domain api.example.com

Run this from inside the git repo — the CLI sends the repo's git remote URL to the daemon. The daemon allocates a host port and wires the front proxy.

3. Push and deploy

git push origin main
stackcube deploy my-api

The CLI streams progress events from the daemon as it fetches the commit, builds the image, and brings up the Compose stack.

Where to go next