Agent Sandbox
The Agent Sandbox is a guardrail layer enforced by the local agent's SecurityGuard. It restricts what the AI Assistant and MCP extensions can read, write or execute on your machine.
Where to configure
Portal → Settings → Agent Sandbox. Settings are pushed to the agent over the WebSocket bridge and re-evaluated on every tool call.
Agent modes
| Mode | What it can do |
|---|---|
| advisor | Read project files, no writes, no MCP, no shell |
| builder | + write files inside the project, browser MCP, chat-safe extensions |
| operator | + full MCP catalog (ops-grade, admin), shell with arg sanitisation |
Mode is per-agent and can be locked by team admins.
Allowed roots
By default, file access is allowed in:
- The project directory (passed via
--project) ~/.xyva/- The OS temp directory
~/Projects(legacy default)
The agent rejects path-traversal attempts (.., symlinks) and any access outside these roots.
Shell argument sanitisation
When operator mode runs shell commands, the agent strips dangerous characters before execution:
; & | ` $ < > ( ) { } [ ] ! # ~ ' "This prevents command injection through AI-generated arguments.
URL guard
Outbound HTTP from agents is restricted to:
- HTTPS only (HTTP refused unless explicitly allowed)
- Allowed-origin list (configurable per-team)
- localhost allowed for
ollama,lm-studio, dev servers
Audit log
The agent keeps the last 250 sandbox events with timestamp, mode, action, and decision. Inspect under Settings → Agent Sandbox → Audit Log or in ~/.xyva/audit.log.
Recommended flow
- Default to advisor for new agents.
- Promote to builder only when you actively want AI-assisted file edits.
- Reserve operator for engineers running ops-grade automations (deploys, infra checks).
- Review the audit log weekly; rotate keys if you spot unexpected calls.