Tools, Approvals, and Sandbox
OpenSquilla tools give the agent useful capabilities. Policy layers, approval surfaces, workspace constraints, and sandbox posture control how those tools are allowed to act.
Use this page before running unattended automation, file edits, shell commands, or channel-connected agents.
For a focused permissions guide, see
approvals-and-permissions.md.
For the current Safe mode and Full access behavior, including guest isolation
and upgrade compatibility, see sandbox-security.md.
Built-In Tool Areas
| Area | Examples |
|---|---|
| Filesystem | read_file, write_file, edit_file, list_dir, glob_search, grep_search, spreadsheet reads. |
| Shell and code | exec_command, background_process, process, execute_code. |
| Git | git_status, git_diff, git_log, git_commit, apply_patch. |
| Web | web_search, web_discover, web_fetch, http_request. |
| Memory | memory_search, memory_save, memory_get, memory_delete. |
| Sessions | sessions_send, sessions_spawn, sessions_list, sessions_history, session_status. |
| Artifacts | publish_artifact. |
| Media | image generation, PDF, TTS, and media helpers. |
| Skills | skill_list, skill_view, skill_create, skill_edit, install_skill_deps. |
| Admin | cron and gateway administration. |
| Channels/platforms | messaging and Feishu/Lark docs, chat, drive, wiki, media, and permission helpers. |
Permission Modes
Use stricter modes when running unattended:
opensquilla agent --permissions restricted -m "Inspect this repo"
Use broader modes only when you trust the task and workspace:
opensquilla agent --permissions full --workspace /path/to/project -m "Run tests and fix failures"
For interactive work, the Web UI approvals surface can pause sensitive tool calls for review. For automation, choose a permission mode and workspace policy before the run starts.
Read: approvals-and-permissions.md
Approval Flow
Sensitive actions may pause for human approval depending on permission mode, tool policy, channel surface, and runtime configuration.
Approvals are most important for:
- filesystem writes;
- shell commands;
- external channel or webhook delivery;
- generated artifacts that will be published;
- actions that affect another service.
Use the Web UI approvals page when you want durable review outside the chat scrollback.
Workspace Controls
Read-side restriction:
opensquilla agent --workspace /path/to/project --workspace-strict -m "Summarize this repo"
Write containment:
opensquilla agent \
--workspace /path/to/project \
--workspace-lockdown \
--scratch-dir /path/to/project/.scratch \
-m "Investigate and prepare a minimal patch"
--workspace-lockdown is intended for automation where writes must stay inside
the workspace or scratch directory.
Sandbox Commands
opensquilla sandbox status
opensquilla sandbox on
opensquilla sandbox full
opensquilla sandbox bypass
opensquilla sandbox reset
Sandbox behavior is platform-dependent. Treat sandbox status and doctor as
the source of truth for the current machine.
Ordinary channel sessions
Admitting a sender or a group does not grant host execution. The Gateway
enables read_file, write_file, edit_file, apply_patch, and execute_code
only after attesting a managed session workspace and an available sandbox.
The same turn-local proof controls tool discovery, dispatch, and the handlers.
It cannot be supplied through a message, model argument, or channel metadata.
The workspace must have strict containment, no additional mounts, and validated directory ownership and identity. Configured project directories, shared roots, and old sessions without a valid managed binding do not qualify. Python runs with an allowlisted environment and no network, using installed libraries. Sandbox startup or execution failure is terminal; execution never retries on the host. Ineligible sessions retain their existing limited tool surface.
This capability currently supports Linux Bubblewrap and macOS Seatbelt.
Windows remains unavailable for ordinary channel authoring until its backend
can enforce the required read isolation. exec_command, background processes,
Git mutations, and elevation remain unavailable to ordinary channel callers.
Verified channel administrators, Web UI, and CLI retain their existing policy
semantics. Group sessions default to per-sender isolation.
Recommended Patterns
| Task | Recommended posture |
|---|---|
| Read-only repo summary | --workspace plus --workspace-strict |
| Local patch with tests | --workspace, --workspace-lockdown, and a scratch dir |
| Chat with possible writes | Web UI with approvals visible |
| Channel-connected agent | Conservative permissions and explicit channel config |
| Provider/debug investigation | Diagnostics on, minimal tool permissions |
Web Safety
OpenSquilla web tools use provider configuration and guardrails. Use provider diagnostics when web search behaves unexpectedly:
opensquilla search status
opensquilla search query "test query"
opensquilla diagnostics on
Search results and fetched pages are external data. They should inform the answer, not override tool policy or user instructions.
For source-backed answers, web_search is the default high-level web tool.
web_discover is lightweight link discovery, web_fetch reads a specific
page, and http_request is reserved for raw HTTP/API requests.
web_fetch and http_request honor HTTP_PROXY / HTTPS_PROXY / ALL_PROXY
only when OPENSQUILLA_TRUST_ENV=1. That opt-in is off by default. Search
providers use the separate search_use_env_proxy setting. web_fetch keeps
DNS pinning through environment proxies unless the separate
OPENSQUILLA_WEB_FETCH_TRUST_PROXY_DNS=1 opt-in delegates DNS and final
destination access control to that proxy. See
configuration.md.
Tool Compression
Large tool results may be compacted before they are shown to the model. This is
normal and protects the active context window. See
features/tool-compression.md.
Artifacts and Media
Tool calls can publish artifacts and generate media. See
artifacts-and-media.md for user-facing artifact,
document, image, PDF, and TTS workflows.
Troubleshooting
If a tool does not run:
-
Check permission posture:
opensquilla sandbox status opensquilla doctor -
Check whether the gateway or channel surface requires approval.
-
Confirm the workspace path is correct.
-
Use diagnostics for repeated failures:
opensquilla diagnostics on
Docs index · Product guide · Improve this page · Report a docs issue