Sandbox Profiles

Profile shape matters more than profile count. Keep normal coding tight, make broader access explicit, and make true bypasses ugly.

Last updated

Architecture
Reality check: profile design is a practical local hardening tool, not a perfect sandbox story. If you can afford the operational overhead, a dedicated VM is still the stronger boundary.

1. Why profiles exist

Profiles are where “the agent should be careful” becomes an actual boundary.

Without profiles, every task inherits the same ambient shell trust: the same files, the same credentials, the same mistake surface. That is exactly what you are trying to reduce.

A good profile system does two things:

  • it maps real task shapes to real access patterns
  • it makes escalations explicit instead of accidental
Profile rule: create tiers for actual work patterns, not for aesthetic symmetry.

2. A good default shape

A simple profile family is enough for most operator setups:

TierPurposeWhat it means
basenormal codingTight sandbox, narrow filesystem, no ambient surprises
pluginextending tools or local pluginsBase + the extra paths genuinely needed for plugin or extension work
unsafebroader host accessStill sandboxed, but with wider local visibility for deliberate debugging or maintenance
rawdogtrue bypassNo sandbox. Deliberate, explicit, ugly.

The names matter less than the meaning. The meanings should be stable.

3. What unsafe should mean

unsafe should not mean “no sandbox.” It should mean “broader host access, still under the kernel sandbox.”

That distinction is load-bearing. If unsafe quietly becomes a bypass, operators stop noticing when they crossed the line.

  • good: broader config visibility, more local state, still bounded by the sandbox
  • bad: ambient credentials, arbitrary browser access, silent no-sandbox execution

If there is a real no-sandbox path, name it so bluntly that nobody can pretend it was an ordinary profile.

4. Why plugin work deserves its own tier

Plugin and extension work is not the same as normal coding. It often needs broader access to local tool state, generated metadata, or helper repos.

That does not mean every normal coding session should inherit those permissions. It means plugin work should have its own deliberate tier.

This is the same reasoning behind local visual inspection helpers: if a capability is real but special, isolate it instead of smearing it across every profile.

5. Make escape hatches obvious

The most dangerous profile mistake is a hidden bypass.

If there is a path that skips the sandbox, it should be:

  • explicitly named
  • rarely used
  • easy to spot in shell history and transcripts
Bad pattern: a “slightly more permissive” profile that quietly becomes the default because it avoids friction.

6. Keep private tiers private

Some operators keep extra maintenance tiers for narrowly-scoped local work. Those are often full of machine-specific paths and personal host assumptions.

Do not turn private maintenance tiers into public defaults just because they exist locally. Public documentation should describe the stable model, not leak private path names or host quirks.

That is why this guide talks about meanings first and private implementation details second.

7. Profile design rules

  • Design tiers around real tasks, not around “completeness.”
  • Keep base tight enough that it stays the default.
  • Give special work its own tier instead of broadening base.
  • Keep unsafe sandboxed.
  • Make the true bypass explicit and ugly.
  • Document the meaning of each tier, not just its name.
  • Remember that profiles are a host-local control, not a substitute for a VM boundary.

If you want the browser example of this philosophy, read visual-inspection. If you want the layer split above profiles, go back to agent-stack.