Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

The path from zero to a running machine. You need an access token — the cps team issues these (invite-only alpha).

1. Install the CLI

curl -fsSL https://cps.run/install.sh | sh

The script downloads the cps binary for your OS/arch and installs it into ~/.local/bin. If that directory isn’t on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Supported: Linux and macOS, x86_64 or arm64. Verify:

cps version

2. Log in

cps login --token <your-token>

The API defaults to https://cps.run. Select your org’s project:

cps project list          # shows the "default" project created for your org
cps project use <prj_id>  # from the list above

3. Launch a machine

cps new ubuntu --name dev --start --wait

Defaults: 1 vCPU, 512 MiB RAM, a 4 GiB disk, and a 24h TTL (the machine auto-deletes after a day so nothing is left running by accident). Override with --cpu, --ram 2G, --disk 10G, --ttl 2h. Use --ttl 0 for a persistent machine that is never auto-deleted.

4. Use it

cps ssh dev                       # root shell over SSH
cps exec dev -- uname -a          # run a one-off command
cps cp ./file dev:/root/          # copy a file in
cps expose dev 8080               # publish a port over public HTTPS
cps metrics dev                   # live CPU / memory
cps ps                            # list your machines

cps expose returns a public URL like https://rte-….cps.run that proxies to the given port inside the machine.

5. Snapshots and backups

The machine must be stopped (cps stop):

cps stop dev
cps snapshot create dev --name base --wait     # fast restore point
cps backup create dev --name daily --wait      # durable off-host copy (S3)
cps snapshot restore <snap> --name dev2 --start --wait

A snapshot is a fast disk image (a restore point). A backup is a durable copy in off-host storage (S3) — it survives host loss and restores on any host in the fleet.

6. Clean up

cps rm dev --yes

Limits & etiquette (alpha)

  • Your org has a resource quota and a machine-count cap. cps will tell you if you hit them.
  • Machines are hardware-isolated (Firecracker + jailer) and cannot see each other.
  • Please don’t use machines for abuse (spam, scanning, mining). This is a private alpha.
  • Questions, bugs, ideas → the @cps_run chat on Telegram.

Troubleshooting

  • cps ssh hangs → Ctrl-C and retry; report persistent hangs in the chat.
  • 401/403 → your token expired or you’re pointed at the wrong project (cps project use).
  • cps whoami shows who you’re authenticated as.