shipyarddocs
shipyarddocs

Guides

The resource guard

Keep a box usable when memory runs short, by stopping idle dev servers and pausing idle agents.

Each box can keep itself usable when memory runs short. The guard is off until you turn it on, in the app (Settings → Boxes → ⋯ → Resource guard) or in ~/.berth/guard.json on the box:

~/.berth/guard.json
{ "enabled": true, "memory_percent": 90, "sustain": "1m", "stop_services": true, "pause_agents": true }
FieldMeaningDefault
enabledTurns it onfalse
memory_percentHow full memory must be, 50 to 9990
sustainFor how long, at most 1h1m
stop_servicesMay stop dev serverstrue
pause_agentsMay pause idle agentstrue
session_memory_gbA memory limit for each session, in GB, whether or not the guard is on; see belownone

session_memory_gb is set in Settings → Boxes, under Browsers and sessions. It applies on Linux boxes with systemd, where each session runs in a scope of its own: a session near it is slowed down, and Shipyard says so in its chat, on its tab and in a notification. Nothing is stopped for it.

What it does

Once memory has stayed above memory_percent for sustain, the guard takes one step, waits 30 seconds, and looks again:

  1. It stops the services of a worktree where no agent is working, the one idle longest first. This frees memory at once.
  2. When none are left, it pauses a worktree whose live sessions are all idle or finished agents. Paused agents use no CPU and the kernel can swap them out; their memory is only freed if it does. Resume them from the Worktrees view.

It never touches an agent that is working or waiting for you, or a plain shell. Each step sends guard.acted (with what it stopped or paused and why) and a notify, so you see it in the app.

The guard reads memory from /proc, so it works on Linux boxes; on a box without it, it stays idle. Changing it runs before:config.change gates.

To react to it yourself, hook guard.acted (see hooks). For what pausing does to a worktree, see pause and resume.

On this page