Turn a written description of a server into a cloud machine, and put an application on it.

Deploy

You describe a deployment in colors.yml. PocketDeploy makes a cloud account match that file: one Ubuntu 24.04 machine, firewall rules, DNS, outbound email, and GitHub access so the application can be delivered. The clouds it knows are Oracle Cloud, DigitalOcean, Google Cloud, and Hetzner.

How you use it

flowchart TB
  yml[colors.yml in git]
  private[.envrc.private and SSH keys<br/>not in git]
  sqlite[(.colors.sqlite<br/>local diary)]
  cmd[pocketdeploy plan / converge]

  yml --> cmd
  private --> cmd
  cmd --> sqlite
  cmd --> cloud[One compute provider]
  cmd --> shared[Cloudflare, Resend, GitHub, ONCE]
  sqlite --> vault[Encrypted VaultContext checkpoint]

Work happens inside a devenv shell (Python, cloud CLIs, OpenSSH, a pinned VaultContext client). The usual loop is plan, then converge. One operator at a time owns a deployment. The lock is local to that machine.

What a deployment includes

Box	What PocketDeploy does with it
Compute	One public IPv4 Ubuntu 24.04 server. Provider is Oracle Cloud (`oci`), DigitalOcean, Google Cloud (`gcp`), or Hetzner (`hcloud`).
Firewall	Rules it created and tagged as its own.
ONCE	Basecamp's app runner, checksum-pinned at v0.3.3, which runs the application container.
DNS	Cloudflare records for the hostname.
Email	Resend, for a sending domain.
GitHub	A deployment environment the app's delivery can use.
Vault	Checkpoints of the controller's state.

Existing networks, cloud projects, and routing stay yours. PocketDeploy does not adopt a stranger's production stack by itself. Switching cloud later means a new deployment plus a separate restore of application data and a DNS cutover.

sequenceDiagram
  participant Op as Operator
  participant PD as PocketDeploy
  participant Cloud as Cloud provider
  participant Once as ONCE on the host
  participant Vault as VaultContext

  Op->>PD: converge colors.yml
  PD->>Cloud: create or match the server and firewall
  PD->>Once: deliver the application
  PD->>PD: record ids in the local diary
  Op->>PD: checkpoint
  PD->>Vault: store encrypted diary, config bindings, SSH authority

A name like <profile>-once-compute is a label. Real identity is the recorded resource id. A missing server is an error, not a cue to create a replacement, when the config says the state must already exist.

What a checkpoint is

The checkpoint can bring the controller back: which resources exist, how they were named, and how to SSH. It does not contain the application's database or uploaded files.