Skip to main content

​
Overview

MeepaGateway can run each agent loop inside a Docker container, isolating LLM-driven code execution from the host system. When isolation is enabled, the entire agent loop — including all tool calls — executes inside a fresh container per message. Isolation is disabled by default. Enable it for agents that run untrusted code or execute shell commands.

​
How It Works

When isolation.enabled = true:
  1. The host receives a message from a connector
  2. A Docker container is spawned running meepagateway agent-run
  3. Message content, secrets, and provider config are passed to the container via stdin as JSON
  4. The agent workspace directory is bind-mounted read-write into the container
  5. The container runs the full agent loop and writes the response JSON to stdout
  6. The host reads the response and sends it back through the connector
  7. The container exits
Only one container runs per agent at a time — a per-agent mutex prevents concurrent SQLite writes from separate container mount namespaces.

​
Runtime Options

​
docker (default when enabled)

Each message spawns a fresh Docker container. Provides strong isolation: filesystem, network, process, and memory limits are all enforced by the container runtime.

​
none

No container. Shell commands run directly on the host process. Use allowed_commands to restrict which commands the agent can execute.
runtime = "none" with an empty allowed_commands list allows the agent to run any shell command as the gateway process user. Only use this in trusted environments.

​
Configuration

Sandbox settings can be set at [agent_defaults.sandbox] (inherited by all agents) and overridden per-agent at [agents.sandbox]. 
agent_defaults:
  sandbox:
    # Disabled by default. Enable for untrusted code execution.
    enabled: true
    runtime: docker       # "docker" | "none"
    timeout: 120s
    image: alpine:3.20    # Docker image for the container
    memory_limit: 256m    # Container memory limit
    network_disabled: true  # Disable network inside container (recommended)
    allowed_commands: []    # "none" runtime only; empty = all allowed

agents:
  # Per-agent override
  - id: coder
    sandbox:
      enabled: true
      runtime: docker
      timeout: 120s
      image: alpine:3.20
      allowed_commands: [python3, node, cargo]

​
Configuration Fields

​
enabled
boolean
default:"false"
Enable Docker-based isolation for this agent’s tool execution.
​
runtime
string
default:"docker"
Isolation runtime. "docker" spawns a container per message. "none" runs on the host with optional command allowlisting.
​
timeout
duration
default:"120s"
Maximum wall-clock time before the container is killed. Supports s, m, h suffixes.
​
image
string
default:"alpine:3.20"
Docker image to use for the isolation container. If empty, an image is auto-built from the host binary.
​
memory_limit
string
default:"256m"
Docker memory limit for the container (e.g. "256m", "1g").
​
network_disabled
boolean
default:"true"
Disable network access inside the container. The agent can still call external LLM APIs (those calls happen on the host, not in the container). Disable only if the agent needs internet access from shell commands.
​
allowed_commands
array
default:"[]"
For runtime = "none" only. Allowlist of executable names the shell tool may run. Empty list allows all commands.

​
File Access

The read_file and write_file tools validate paths against allowed_dirs regardless of sandbox settings. This is enforced at the application level, not by Docker: 
agent_defaults:
  allowed_dirs: [/tmp/meepa-workspace]

agents:
  - id: coder
    allowed_dirs: [/home/user/projects]
Empty allowed_dirs means unrestricted file access (default).

​
Auto-Built Images

If image is empty or the specified image does not exist locally, MeepaGateway auto-builds a minimal image containing the gateway binary. This ensures the container can run meepagateway agent-run without a separate installation. The sandbox image build status is visible in the Captain Dashboard under Settings → Sandbox. You can also manage it via CLI: 
# Build the sandbox image manually
meepagateway sandbox build

# Check sandbox status
meepagateway sandbox status

​
Security Notes

  • Containers run with no host mounts except the agent workspace directory
  • network_disabled = true (default) blocks outbound network from shell commands
  • Memory is capped by memory_limit — containers exceeding this are OOM-killed
  • Containers exit after each message — no persistent container processes
  • The host process handles all connector I/O and LLM API calls; only tool execution is isolated
The inject_credentials_env and redact_secrets options (when available) control whether credentials are passed into the container and whether secrets are stripped from tool output before reaching the LLM.