Configuration

pier setup writes ~/.config/pier/config.toml. Change any setting later from the app’s settings page. Run pier and press s.

The settings page is one page grouped into Cloud, New sessions, Idle & cost, Speed, and Appearance. It shows only the active cloud’s fields, each with a line on what it changes, validates values before saving them, and leaves setup- and bake-managed values alone. Changes apply to new sessions; existing sessions keep the cloud and machine they were built with.

driver = "aws-ec2"
idle_timeout = "30m"      # detached and quiet this long -> park ("never" disables)
unattended_cap = "8h"     # parks even while busy ("never" disables)
theme = "teal"            # accent color: teal navy violet emerald orange crimson pink amber graphite

[aws]
profile = "default"
region = "eu-central-1"
instance_type = "t4g.medium"   # machine for new sessions
disk_gib = 40
subnet = ""                    # optional: orgs without a default VPC
direct = true                  # ssh straight to the VM. false forces the SSM tunnel

[gcp]                          # when driver = "gcp-gce"
project = "my-project"
zone = "europe-west3-a"
machine_type = "e2-medium"
disk_gib = 40

[speed]                        # what a speed profile presets (fast/lean/minimal)
pool_size = 1                  # per baked repo; parked, disk-only cost
bake_reminders = true          # suggest `pier bake`; never automatic
image_repo = true              # bake prebuilds the repo (false = toolchains only)
reminder_age = "30d"           # remind when an image gets this old

[pool]
# max_age = "14d"              # pooled sessions recycle at this age

Keys

Key	Default	Meaning
`driver`	`aws-ec2`	the cloud driver: `aws-ec2` or `gcp-gce`
`idle_timeout`	`30m`	detached and quiet this long parks the VM, `never` disables
`unattended_cap`	`8h`	parks even while busy, so a looping agent can’t burn compute for days
`theme`	`teal`	the app’s accent color: `teal`, `navy`, `violet`, `emerald`, `orange`, `crimson`, `pink`, `amber`, or `graphite`
`aws.profile`		the AWS CLI profile pier calls with
`aws.region`		where sessions run
`aws.instance_type`	`t4g.medium`	machine for new sessions
`aws.disk_gib`	`40`	EBS disk size per session
`aws.subnet`		optional, for orgs without a default VPC
`aws.direct`	`true`	ssh straight to the instance’s public IP, port 22 open to your IP only, SSM tunnel as fallback. `false` forces the tunnel
`gcp.project`		the GCP project sessions run in
`gcp.zone`	`europe-west3-a`	where sessions run
`gcp.machine_type`	`e2-medium`	machine for new sessions
`gcp.disk_gib`	`40`	boot disk size per session
`speed.pool_size`	`1`	parked, set-up sessions each baked repo keeps (Warm pools)
`speed.bake_reminders`	`true`	suggest `pier bake` when it would help; pier never bakes on its own
`speed.image_repo`	`true`	a bake prebuilds the repo; `false` keeps images to toolchains
`speed.reminder_age`	`30d`	remind when a repo’s image gets this old
`pool.max_age`	`14d`	pooled sessions older than this recycle

The speed profile (Fast, Lean, Minimal) is a preset for speed.pool_size and speed.bake_reminders. Change either and the profile reads Custom. See Setup.

Per-session overrides beat the config: --idle, --cap, and --no-pool at create time, and pier pool set <n> for one repo’s pool size.

Managed sections

Some sections are managed by pier, not by hand:

[aws.baked_amis] and [gcp.baked_images] map repo basenames to baked images. pier bake writes them, pier teardown sweeps the images.
[images.<repo>] records when each repo was baked, whether the repo was included, and fingerprints of its .pier scripts. It feeds the rebake reminders.
[pool.sizes] holds per-repo pool sizes written by pier pool set.
[secrets] holds the manifest of files and dirs under $HOME copied one-way into each session at create, plus an optional claude_oauth_token from claude setup-token (the macOS Keychain escape hatch, injected as CLAUDE_CODE_OAUTH_TOKEN in sessions).