Session Profiles

What a profile controls

profiles:
  worker:
    vars:
      hide: [AWS_*, GITHUB_TOKEN]
    processes:
      list: workspace
      kill: session
      max: 8
    command_limits:
      grep: {max_lines: 200}
    network:
      allowed_domains: ["*.github.com"]
    policy:
      pre_command:
        - {script: ./guard.py, runtime: monty}

processes: {list: workspace, max: 64}
profiles:
  batch:
    processes: {max: 512}

Example: a research agent

mounts:
  /data:
    vfs: ram

profiles:
  researcher:
    cwd: /data
    mounts:
      /data:
        mode: read
    paths:
      hide: [/data/private]
    commands:
      allow: [ls, cat, grep, find, stat, pwd]

profile: researcher

Use a profile

• A session keeps its old rules until you move it onto the new profile.
• A moved session keeps its working directory, variables and history.
• workspace.yaml is never rewritten.
• An agent cannot do this from inside a session: no builtin, MCP tool or RPC method changes a profile.

Rule matching

Commands

• A pattern matches token prefixes: git push matches git push origin main.
• Spelling and order matter: rm -rf does not match rm -r -f or rm --recursive --force.
• A * token matches any token. A trailing * adds nothing.
• Without commands.allow, there is no allow list. allow: [] allows no installed tool.
• commands.allow does not cover shell functions, executed paths or direct VFS calls.
• The shell’s tests count as commands under their own names. An allow list admits [ ] only if it names [, and [[ ]] only if it names [[.
• A path rule judges the file operand of -e, -f or -nt the same way in test, [ and [[, however the operand is spelled.

Ask and deny

commands:
  allow: [rm]
  ask:
    - {commands: {rm: ["/data/review/*"]}, reason: deletes need review}
  deny:
    - {commands: {rm: ["/data/*"]}, reason: data is retained}

• For each path, the rule with the deeper literal path wins. At equal depth, deny wins.
• Here rm /data/review/note.txt asks for approval despite the broader deny, and rm /data/other.txt is denied.
• A command with several paths must pass the check for each one.
• Ask and deny control what a command may do. The paths stay visible.

• a line whose working directory or paths are in that mount;
• a walk or a move of a directory that holds the mount (grep -r, ls -R, mv);
• each entry inside the mount that a line reaches on its own (cp -r, chmod -R).

Hide and show paths

• paths.hide makes a path look absent. paths.show reopens a more specific path inside it.
• paths.hide and ask and deny path entries take absolute paths or slashless name patterns such as *.pem, in mount sections too.
• paths.show takes absolute paths only.
• A literal path covers everything under it. Globs use *, ? and [, and * can cross /.
• A rule that names only paths also applies to direct VFS calls.
• Moving a directory that holds a hidden path, or one the session reaches only through a paths.show below it, is refused with Permission denied. The hidden content would come into view.

What a hidden path hides

• Command output: commands and CLIs leave it out of what they print from their own data, and out of their counts and totals. git status, git ls-files, git diff --stat and git log --name-only neither name nor count a file another session staged under it.
• Links: a link that leads into it is hidden too. readlink -f, test -L, ln, touch -h, chown -R and find -newer meet it as a name that is not there.
• Git history: no revision ever held it.
  • git show HEAD:secret.txt answers as for a path never committed.
  • git log -S finds nothing in it.
  • An object id stored only there names nothing.
• Checkouts and branch switches: they leave a hidden file as it is.
  • An edit to it does not block the switch, and git’s refusal does not name it.
  • A switch that would remove it, by writing a file where its directory stands, is refused. The refusal names only the visible path.