Docs navigation
Docs / Tools, Approvals, and Sandbox

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

AreaExamples
Filesystemread_file, write_file, edit_file, list_dir, glob_search, grep_search, spreadsheet reads.
Shell and codeexec_command, background_process, process, execute_code.
Gitgit_status, git_diff, git_log, git_commit, apply_patch.
Webweb_search, web_discover, web_fetch, http_request.
Memorymemory_search, memory_save, memory_get, memory_delete.
Sessionssessions_send, sessions_spawn, sessions_list, sessions_history, session_status.
Artifactspublish_artifact.
Mediaimage generation, PDF, TTS, and media helpers.
Skillsskill_list, skill_view, skill_create, skill_edit, install_skill_deps.
Admincron and gateway administration.
Channels/platformsmessaging 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.

TaskRecommended posture
Read-only repo summary--workspace plus --workspace-strict
Local patch with tests--workspace, --workspace-lockdown, and a scratch dir
Chat with possible writesWeb UI with approvals visible
Channel-connected agentConservative permissions and explicit channel config
Provider/debug investigationDiagnostics 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:

  1. Check permission posture:

    opensquilla sandbox status
    opensquilla doctor
  2. Check whether the gateway or channel surface requires approval.

  3. Confirm the workspace path is correct.

  4. Use diagnostics for repeated failures:

    opensquilla diagnostics on

Docs index · Product guide · Improve this page · Report a docs issue

Edit this page on GitHub OpenSquilla docs · synced from main