How it works

A session is one VM plus its persistent disk, tagged and namespaced by your caller identity. On AWS, pier keeps the complete STS ARN, including the Identity Center user segment of an assumed-role ARN, so a team can share one permission-set role without sharing sessions. On GCP it uses your authenticated principal. All state lives in those tags and on the disk. pier ls is one filtered describe call, and there is nothing else to operate, back up, or pay for.

laptop                              AWS account (yours)
──────                              ───────────────────
pier CLI/TUI ── aws cli ──────────▶ EC2 API        (create/stop/start/tags)
     │                              ┌─────────────────────────┐
     └── ssh ─────────────────────▶ │ session VM               │
         (direct to its public IP,  │  tmux ▸ claude / codex   │
          SSM tunnel as fallback)   │  pier-supervisor         │
                                    │  └─ parks the VM when    │
                                    │     detached and quiet   │
                                    └─────────────────────────┘

GCP is the same picture with gcloud, the GCE API, and Google’s IAP tunnel in place of SSM.

The supervisor

The supervisor samples every 5 seconds for attached (tmux clients, or a live forwarded TCP connection) and busy (a running setup script, agent process-tree CPU, recent pty output):

• attached or busy resets the idle clock
• detached and quiet past idle_timeout parks
• detached but busy past unattended_cap parks anyway, so a looping agent can’t burn compute for days

Parking is the VM running shutdown -h now, with the instance configured to stop rather than terminate. The supervisor holds no credentials and calls no APIs. It beacons state to /run/pier/status.json, which ls, the TUI, and pier proxy read.

Fast repo transfer, GitHub-first

Tunnels are slow (the SSM one moves about 1 MB/s), so anything big avoids them:

• Base commit on a GitHub origin: the VM fetches straight from GitHub, only secrets ride the tunnel.
• Local-only commits: a thin delta bundle through the tunnel.
• Anything else: a full-history bundle, slow but universal.
• Uncommitted edits to tracked files: one git patch, applied after checkout.

Design decisions

The choices contributors should know before proposing changes:

• No control plane, ever. State lives in instance tags. Adding a server, database, or laptop daemon needs an extraordinary reason.
• The cloud CLI, not the SDK. aws and gcloud are already required for their tunnels, and SSO, profiles, and MFA come with them for free.
• No cloud credentials in the VM. Parking is the VM shutting itself down. Resize is human-triggered.
• One transport. Attach, exec, file push, and port forwards are all OpenSSH, straight to the VM or through the cloud’s tunnel.
• Guarded cloud-init, identical on stock and baked images. Baking is an optimization, never a requirement.
• Images are toolchains, sessions are state.
• Dirty state travels as a git patch, not rsync. Binary-safe, reviewable, applied atomically after checkout.
• Truth over optimism in states. pier reports what is, not what the cloud claims.
• pier ls stays plain (pipeable). The TUI is the pretty view.

The full design, including the settled trade-offs and measured spike numbers, lives in docs/SPEC.md.