Skip to content
pier pier

Sessions

A session is one EC2 instance plus its EBS disk, created from a repo and a branch. All state lives in instance tags and on the disk.

Creating

Section titled “Creating”

From inside a git repo:

pier <branch> [base]

The session checks out <branch> off base (default HEAD), applies your uncommitted edits as a git patch, carries the files .pier-include lists, and runs .pier-setup.sh in its own tmux window. Then it attaches.

Flags:

-d, --detach          create without attaching
--idle <dur|never>    idle self-park timeout (default 30m)
--cap <dur|never>     unattended runaway cap (default 8h)
--no-park             shorthand for --idle never

Or press n in the TUI. TUI creates run in the background and the row flips when ready.

States are honest

Section titled “States are honest”

EC2 says “running” long before a session is usable, so pier doesn’t:

  • A session lists as creating until the bootstrap’s last act writes a pier:ready tag.
  • Attaching early gets a plain “still setting up”, not a raw connection error.
  • (setup running) and (setup failed) surface the setup script outcome.
  • working (strained) flags sustained cpu or memory pressure (kernel PSI).
  • A create that fails cleans up its own instance.

Parking and resuming

Section titled “Parking and resuming”

An in-VM 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

A parked session costs disk-only prices, about $3-4 a month. Attach to resume:

$ pier attach checkout-flow
resuming checkout-flow (~20-30s)...

Files, git state, and installed tools survive parking. Running processes do not.

Pinning

Section titled “Pinning”

Disable idle self-park for a session that should stay up:

pier keep <session>

Or press p in the TUI. The unattended cap still applies unless created with --cap never.

Destroying

Section titled “Destroying”
pier rm <session> [-f]

Destroys the session and its disk. Or press d in the TUI.