# Tools and sandbox execution

> Tool categories, Docker-isolated terminal and file tools, network search tools, barrier tools done and ask, timeouts, and default images for general vs pentest work.

- Repository: vxcontrol/pentagi
- GitHub: https://github.com/vxcontrol/pentagi
- Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5
- Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt

## Source Files

- `backend/pkg/tools/registry.go`
- `backend/pkg/tools/executor.go`
- `backend/pkg/tools/terminal.go`
- `backend/pkg/docker/client.go`
- `backend/docs/docker.md`
- `backend/pkg/config/config.go`
- `backend/docs/flow_execution.md`

---

---
title: "Tools and sandbox execution"
description: "Tool categories, Docker-isolated terminal and file tools, network search tools, barrier tools done and ask, timeouts, and default images for general vs pentest work."
---

Agents act through a named tool registry (`backend/pkg/tools`) executed by a per-flow `customExecutor`. Environment tools (`terminal`, `file`) run inside a primary Docker container named `pentagi-terminal-<flowID>`; network search and memory tools call host-side integrations when configured; barrier tools (`done`, `ask`) stop the agent loop with a success or wait outcome.

## Runtime architecture

```mermaid
flowchart TB
  subgraph agents [Agent executors]
    PA[Primary]
    PT[Pentester / Coder / Installer]
    SR[Searcher]
  end

  subgraph tools_pkg [backend/pkg/tools]
    REG[registry definitions]
    CE[customExecutor.Execute]
    TERM[terminal + file handlers]
    NET[search_network handlers]
    BAR[barrier handlers]
  end

  subgraph docker_pkg [backend/pkg/docker]
    DC[DockerClient.RunContainer]
    EXEC[ContainerExecCreate / Attach]
  end

  subgraph sandbox [Primary container]
    WORK["/work volume"]
    SH["sh -c command"]
  end

  PA --> CE
  PT --> CE
  SR --> CE
  REG --> CE
  CE --> TERM
  CE --> NET
  CE --> BAR
  TERM --> EXEC
  CE --> DC
  DC --> sandbox
  EXEC --> SH
  WORK --- SH
```

On flow prepare, `flowToolsExecutor.Prepare` reuses a running primary container or creates one with the flow-selected image, `NET_RAW` (and optional `NET_ADMIN`), and a bind/volume at `/work`. User uploads and resources are synced into `/work/uploads` and `/work/resources`.

## Tool categories

`GetToolType` maps every registry name to a `ToolType`. The executor uses the type for Langfuse observation kind and for barrier detection.

| `ToolType` | String | Tools |
|---|---|---|
| `EnvironmentToolType` | `environment` | `terminal`, `file`, assistant flow-control (`get_flow_status`, `stop_flow`, `submit_flow_input`, `patch_flow_subtasks`, `wait_flow_completion`) |
| `SearchNetworkToolType` | `search_network` | `browser`, `google`, `duckduckgo`, `tavily`, `traversaal`, `perplexity`, `searxng`, `sploitus` |
| `SearchVectorDbToolType` | `search_vector_db` | `search_in_memory`, `search_guide`, `search_answer`, `search_code`, `graphiti_search` |
| `StoreVectorDbToolType` | `store_vector_db` | `store_guide`, `store_answer`, `store_code` |
| `AgentToolType` | `agent` | `search`, `maintenance`, `coder`, `pentester`, `advice`, `memorist` |
| `StoreAgentResultToolType` | `store_agent_result` | `search_result`, `maintenance_result`, `code_result`, `hack_result`, `memorist_result`, `enricher_result`, `report_result`, `subtask_list`, `subtask_patch` |
| `BarrierToolType` | `barrier` | `done`, `ask` |

Optional tools are registered only when `IsAvailable()` is true (API keys, scraper URLs, embedder, Graphiti client, and related flags).

## Which agents get which tools

Executors are built in `flowToolsExecutor` with different definition sets:

| Executor | Direct sandbox | Network search | Barriers / terminal results |
|---|---|---|---|
| **Primary** | No `terminal`/`file` | Via `search` agent tool | `done` always; `ask` if `ASK_USER=true` |
| **Installer** | `terminal`, `file` | `browser` (+ guides) if available | `maintenance_result` |
| **Coder** | `terminal`, `file` | optional `browser` | `code_result` |
| **Pentester** | `terminal`, `file` | optional `browser`, `sploitus` | `hack_result` |
| **Searcher** | No sandbox | Engines + `browser` when configured | `search_result` |
| **Assistant** | `terminal`, `file` | optional `browser`; optional agent tools if `UseAgents` | Flow-management tools when handlers injected |

Primary orchestrates; specialists hold the Docker shell and search engines.

## Docker sandbox

### Primary container

- **Name:** `pentagi-terminal-<flowID>` (`PrimaryTerminalNamePrefix`)
- **Type:** `ContainerTypePrimary`
- **Entrypoint:** `tail -f /dev/null` (idle shell host for `docker exec`)
- **Working directory:** `/work` (`WorkFolderPathInContainer`)
- **Capabilities:** always `NET_RAW`; add `NET_ADMIN` when `DOCKER_NET_ADMIN=true`
- **Data:** host path under `DATA_DIR/flow-<id>` (or a named volume) bind-mounted to `/work`
- **Ports (bridge mode):** two TCP ports per flow from base `28000` via `GetPrimaryContainerPorts(flowID)`
- **DinD:** when `DOCKER_INSIDE=true`, the host Docker socket is mounted into the container

### Image selection and fallbacks

| Config key | Default | Role |
|---|---|---|
| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | General default / pull-create fallback (`GetDefaultImage`) |
| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | Prompted to the image chooser as the pentest baseline |

Flow start selects an image (prompt type `image_chooser`, with both defaults in template context). `RunContainer` pulls the chosen image; on pull or create failure it falls back to `DOCKER_DEFAULT_IMAGE` and retries.

### Related Docker settings

| Variable | Default | Effect |
|---|---|---|
| `DOCKER_HOST` | From Docker env / socket | Daemon connection |
| `DOCKER_SOCKET` | Auto-detected or `/var/run/docker.sock` | Socket path when `DOCKER_INSIDE` |
| `DOCKER_NETWORK` | empty | Custom bridge name, or `host` for host network mode |
| `DOCKER_PUBLIC_IP` | `0.0.0.0` | Host IP for published ports |
| `DOCKER_WORK_DIR` | empty | Override host work root for binds |
| `DATA_DIR` | `./data` | Local flow file root |

## Environment tools

### `terminal`

Runs one blocking (or detached) shell command in the primary container via `ContainerExecCreate` / `Attach`:

```text
sh -c <input>
```

| Argument | Required | Behavior |
|---|---|---|
| `input` | yes | Command string |
| `cwd` | yes | Working directory; empty defaults to `/work` |
| `detach` | yes | `true` for interactive/long-running (listeners, shells, servers); returns quickly, little or no captured output |
| `timeout` | yes | Seconds; see [Timeouts](#timeouts) |
| `message` | yes | Engagement-log commentary |

Only one command is executed per call. Stdin/stdout are logged through `TermLogProvider`. Handler errors are swallowed into a result string so the agent loop can continue.

### `file`

| `action` | Behavior |
|---|---|
| `read_file` | `CopyFromContainer` + tar extract; max file size **100 MB** |
| `write_file` | Tar stream + `CopyToContainer`; mode `0600` |

`path` must be absolute inside the container. User materials appear under `/work/uploads` and `/work/resources` after prepare-time sync.

## Network search tools

Registered on Searcher (and partially on other agents) when available:

| Tool | Typical gate |
|---|---|
| `browser` | `SCRAPER_PRIVATE_URL` / `SCRAPER_PUBLIC_URL` |
| `google` | Google CSE credentials |
| `duckduckgo` | `DUCKDUCKGO_ENABLED` (default true) |
| `tavily` | `TAVILY_API_KEY` |
| `traversaal` | Traversaal key |
| `perplexity` | Perplexity key |
| `searxng` | Searxng URL |
| `sploitus` | Always constructible (HTTP exploit search) |

Shared search args: `query` (prefer English for indexed web), `max_results` (1–10), `message`. External HTTP calls also respect proxy and global client timeout settings. Full enablement matrix: [Search engines](/search-engines).

## Barrier tools

Barriers end the agent tool-call loop. `IsBarrierFunction` checks the executor’s barrier set; Primary wires:

| Tool | When registered | Payload | Effect |
|---|---|---|---|
| `done` | Always on Primary | `success`, `result`, `message` | Subtask finished (`PerformResultDone`) |
| `ask` | Only if `ASK_USER=true` | `message` (question) | Wait for user input (`PerformResultWaiting`) |

Specialist “result” tools (`hack_result`, `code_result`, `search_result`, …) are barriers for those executors and return control to the caller.

```text
ASK_USER=false  →  Primary barriers: { done }
ASK_USER=true   →  Primary barriers: { done, ask }
```

Resume after `ask`: user input via UI / API, or Assistant `submit_flow_input` when flow-manager handlers are injected.

## Timeouts

### Terminal execution

| Constant / config | Value | Meaning |
|---|---|---|
| `TERMINAL_TOOL_TIMEOUT` | **1200** s default | Server default for `terminal` |
| Explicit max | **10800** s (3 h) | Upper bound for agent-requested timeouts |
| Extra slack | **+5** s | Added around configured/requested limits for cleanup |
| Detach quick-check | **500** ms | How long detach mode waits before returning “still running” |

Rules implemented in `terminal.normalizeExecTimeout` / `configuredExecTimeout`:

1. Configured default ≤ 0 or > 3 h is treated as **3 h** (commands are never unbounded).
2. Agent `timeout` of `0`, negative, or above the allowed ceiling falls back to the configured default (+ extra).
3. Positive values within range are used (+ extra).
4. On timeout, the handler returns partial output and hints: use `detach=true` for interactive work, or wrap long batch jobs with the shell `timeout` utility.

### Other tool timeouts

| Surface | Bound |
|---|---|
| Result summarization | Large `terminal` / `browser` results over **16 KB** may be summarized or truncated |
| `wait_flow_completion` | Default **60** s; max **3600** s |
| Global HTTP client | Configured separately for LLM and search providers |

## Execution path (single tool call)

```text
LLM tool_call
  → customExecutor.Execute
      → log message + toolcall row
      → handler (terminal / search / barrier / …)
      → optional summarize (terminal, browser)
      → optional storeToolResult for allow-listed tools
      → update msg + toolcall success/failure
  → if IsBarrierFunction → stop agent loop
```

Allow-listed for long-term memory storage include `terminal`, `file`, major search engines, and several agent tools.

## Failure modes

| Symptom | Likely cause |
|---|---|
| `terminal is not available` / container not operational | Primary container missing, stopped, or prepare failed |
| Pull/create falls back to `debian:latest` | Chosen or pentest image unavailable; check registry and disk |
| Network tools missing from tool list | `IsAvailable()` false — keys/URLs not set |
| `ask` never offered | `ASK_USER` left at default `false` |
| Advanced nmap / raw networking weak | `DOCKER_NET_ADMIN=false` (only `NET_RAW`) |
| Host network isolation reduced | `DOCKER_NETWORK=host` |
| Command timeout with partial output | Timeout too low for batch job; use shell `timeout` or `detach=true` |
| File read error on large artifact | File exceeds **100 MB** read limit |
| Missing `/work/uploads` content | Prepare sync failed or files added after last prepare without re-sync |

## Configuration quick reference

<ParamField body="ASK_USER" type="boolean">
Enable Primary `ask` barrier. Default `false`.
</ParamField>

<ParamField body="TERMINAL_TOOL_TIMEOUT" type="integer">
Default terminal timeout in seconds. Default `1200`.
</ParamField>

<ParamField body="DOCKER_DEFAULT_IMAGE" type="string">
Fallback / general image. Default `debian:latest`.
</ParamField>

<ParamField body="DOCKER_DEFAULT_IMAGE_FOR_PENTEST" type="string">
Pentest baseline image. Default `vxcontrol/kali-linux`.
</ParamField>

<ParamField body="DOCKER_NET_ADMIN" type="boolean">
Grant `NET_ADMIN` on the primary container. Default `false`.
</ParamField>

<ParamField body="DOCKER_INSIDE" type="boolean">
Mount Docker socket for Docker-in-Docker style management. Default `false`.
</ParamField>

## Next

<CardGroup>
  <Card title="Tools reference" href="/tools-reference">
    Full named registry, argument shapes, and assistant flow-control tools.
  </Card>
  <Card title="Docker sandbox and workers" href="/docker-sandbox-workers">
    Socket, network, multi-host worker nodes, and custom images.
  </Card>
  <Card title="Search engines" href="/search-engines">
    Keys, scraper URLs, proxy, and which network tools light up.
  </Card>
  <Card title="Agents and supervision" href="/agents-and-supervision">
    Specialist roles, monitoring, and tool-call hard limits.
  </Card>
  <Card title="Memory and knowledge" href="/memory-and-knowledge">
    Vector memory tools, `/work` files, and Graphiti search.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    Full Config struct and .env defaults for Docker and tools.
  </Card>
</CardGroup>