Skip to main content

Sandboxed Execution

What sandboxing means​

When Manasvi executes a tool, it doesn't run the tool with full access to the system. It runs it in a sandbox — an isolated environment with explicitly declared and enforced constraints.

A sandboxed tool can only:

  • Access the network destinations listed in its manifest
  • Read/write the filesystem paths it declared
  • Produce output up to the configured size limit
  • Run for up to the configured time limit

Anything outside those declarations is blocked at the sandbox level — not just discouraged.

Why sandboxing matters for AI agents​

The AI model may be instructed (or manipulated) into requesting a tool to do something beyond its intended scope. For example:

  • A web fetch tool might be asked to call an internal API that wasn't the intended target
  • A file read tool might be asked to read a sensitive file outside the expected directory
  • A shell command tool might be asked to exfiltrate data over the network

Without sandboxing, the tool would do whatever the model requested. With sandboxing, the declared constraints are enforced regardless of what the model requests.

Tool manifests as contracts​

Each tool's manifest declares its execution constraints:

Tool ID: tool.http-fetch
Sandbox mode: restricted_remote
Network profiles:
  - allowlist: [http, https on standard ports 80/443]
Filesystem access: none
Output size limit: 65KB
Time limit: 30s

This manifest is the contract between the tool and the sandbox. The sandbox enforces it; the tool cannot escape it.

Sandbox modes​

ModeNetworkFilesystemTypical use
noneNo accessNo accessPure computation tools
restricted_localNoneDeclared paths onlyLocal file tools
restricted_remoteAllowlisted URLs onlyNoneHTTP fetch, web search
privilegedFullFullShell command (always requires approval)

Privileged mode is reserved for explicitly high-risk tools that always require human approval.

Output limits​

Tool output is capped to prevent:

  • The model's context window being flooded with unwanted content
  • Large data exfiltration disguised as tool output
  • Resource exhaustion from unbounded output

Default cap: 65KB. Output exceeding the limit is truncated, and the truncation is noted in the execution record.

Isolation level (important)​

The current sandbox enforces constraints at the JavaScript level: it runs the tool in a separate child process and intercepts Node's fs, net, http, https, and fetch APIs. This is not OS-level containerization.

What this means in practice:

  • Filesystem and network limits apply to code using Node's standard library.
  • They can be bypassed by native addons (*.node binaries), worker threads that re-enter unpatched globals, or node:vm contexts. A tool that spawns a native OS process is not contained.
  • For untrusted or native-process workloads you must run the execution manager inside an OS-isolated environment (container with a seccomp profile, gVisor, or a microVM) and set EXECUTION_SANDBOX_CONTAINERIZED=true.

To make this safe by default, a tool manifest can declare runtimeHints.requiresNativeIsolation: true. The execution manager refuses to run such a tool unless it is running in a containerized environment (SANDBOX_REQUIRES_NATIVE_ISOLATION, fail-closed). The built-in tool.shell-command sets this flag because it spawns a native process.

This is tracked as security finding SF-003; full OS-level isolation is planned (see the container execution plan in the internal docs).

What the sandbox doesn't cover​

Sandboxing constrains the execution environment, but it doesn't eliminate the need for policy evaluation. A tool that is within its declared constraints can still be inappropriate in a given context (wrong user, wrong resource, policy violation).

Policy evaluation and sandboxing are complementary controls — both are needed.