Sandboxes¶
A sandbox is a reusable configuration. It defines what an agent can use: models, packages, MCP tools, skills and network hosts. A sandbox is not a separate machine.
A Sandbox Holds Five Kinds of Settings¶
| Setting | What it controls |
|---|---|
| Models | Which models the agent can call, and which one is the Default model |
| Packages | The software the agent can run, such as jq or python3. AgentZ installs it from nixpkgs, a public package collection |
| MCP tools | Which tools of an MCP connection the agent can use |
| Skills | Which saved instructions the agent can load |
| Allowed hosts | Which outside addresses the agent can reach directly |
An MCP connection is a link to an outside tool server. You add it once, then each sandbox picks the tools it exposes. See MCP connections.
Each Agent Uses Exactly One Sandbox¶
An agent uses one sandbox. Many agents can use the same sandbox. When you update a sandbox, every agent that uses it picks up the change. A running agent restarts to apply it.
A sandbox can live in the organization or in a workspace. A workspace can inherit organization sandboxes, and its agents can use them. See Organizations and workspaces.
Tool Access Is Set per Tool in Each Sandbox¶
For each MCP tool in a sandbox, you choose one of three states:
- Not exposed. The agent cannot see the tool.
- Exposed, consent not required. The agent runs the tool without asking.
- Exposed, consent required. The chat asks you first and offers Deny, Always allow and Allow once.
In a workflow run, no one is in the chat. AgentZ allows consent-required tools automatically.