Skip to main content
An agent should reach exactly what its task needs. In Mirage, the files it sees, the commands and CLIs it may run and the credentials its tools use are all set in one workspace config, on the server, and the agent cannot change them. This example gives an analyst agent read access to a bucket and a Slack CLI it can read with but not post from.

Setup

The workspace has an S3 bucket at /data, a RAM folder at /scratch, and the gh and slack CLIs. Their credentials come from AWS Secrets Manager, 1Password and the server’s environment, and the agent never sees them. The analyst profile sets what the agent can see and run.
workspace.yaml

File Visibility Control

paths.hide makes /data/secrets and every *.pem absent, and paths.show brings back /data/secrets/README.md. A hidden file is not refused, it does not exist, whichever way the agent looks for it. Shell commands:
Python commands:
VFS calls:

Commands Control

commands.allow lists the only commands the session runs, so everything an analyst does not need, such as rm, sed or curl, is off. For a CLI the list names single verbs, so slack reads messages and members but never posts, edits or uploads, and gh lists and views pull requests but cannot merge one or call gh api. The agent reads the shell’s own Permission denied and exit 126; the reason reaches the host on the result’s decision, shown under each line:

Agent Profile

An agent profile is a named set of rules under profiles:. A session takes a profile when it is created, and every line, file call and CLI in that session follows it, however the agent connects. A profile can only narrow the workspace, never widen it, so one workspace can serve agents with different reach. The analyst profile above:
  • cwd and env start the session in /data with TEAM set.
  • mounts keeps /data read-only, though the workspace may write it.
  • paths and commands are the rules from the two sections above.
A profile also takes vars, network, processes, command_limits and policy; see Session Profiles.

Connect to a profile session

With the workspace on a Mirage server as secured, the agent reaches the same session over HTTP, MCP or SSH:
Create the session under the profile, then run lines in it:
MCP and SSH add the policy denied: line for the agent. See Access for every way in.

Learn more