How it works

A session is one EC2 instance plus its EBS disk, tagged and namespaced by your caller identity (pier:user is your STS ARN, so a team shares one account with zero collisions). All state lives in those tags and on the disk. pier ls is a filtered describe-instances, 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   │
                                    └─────────────────────────┘

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

The SSM tunnel moves about 1 MB/s, so anything big avoids it:

• 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 EC2 tags. Adding a server, database, or laptop daemon needs an extraordinary reason.
• The AWS CLI, not the SDK. The CLI is already required for the SSM plugin, and SSO, profiles, and MFA come with it 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 over the SSM fallback.
• 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 EC2 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.