Dependencies & Checks

Some capabilities need packages, system tools, or setup scripts before they work. Declare those under dependencies: and the sandbox provisioner installs them before the runtime starts. Declare checks: and the loader verifies the environment every time the capability loads.

dependencies:
  python: [requests, httpx]
  packages: [libssl-dev]
  scripts: [scripts/setup.sh]

checks:
  - name: python-available
    command: python --version
  - name: subfinder-installed
    command: command -v subfinder

Together they cover the install step (once per sandbox) and the verification step (every load).

Dependencies

Three categories, all sandbox-specific. Local installs ignore them — you manage your own Python env.

For Python MCP servers and subprocess workers, prefer shipping each as a self-contained PEP 723 script and invoking it through uv run — the same file works locally and in a sandbox without touching dependencies.python. See MCP servers and Workers for the pattern.

Field	Installed by	Use for
python	pip	Python packages the capability imports
packages	apt-get	System packages (Debian-based sandboxes)
scripts	Shell	Arbitrary setup scripts relative to the capability root

dependencies:
  python:
    - requests>=2.31
    - dnspython==2.6.1
  packages:
    - libpcap-dev
    - nmap
  scripts:
    - scripts/install_pd_tools.sh
    - scripts/seed_rules.sh

Scripts run in order, with the capability root as their working directory. Non-zero exit codes fail the install.

Checks

Checks are shell commands that must exit 0 for the capability to be considered healthy. They run at capability load time with a 5-second timeout per check.

checks:
  - name: python-available
    command: python --version
  - name: sqlite-fts5
    command: python -c "import sqlite3; conn = sqlite3.connect(':memory:'); conn.execute('create virtual table t using fts5(x)')"
  - name: subfinder
    command: command -v subfinder >/dev/null 2>&1

Each check produces a component health entry with kind="check". Failed checks surface in the TUI capability manager with the command and exit code. The capability still loads — failed checks don’t block it, but operators see the red signal.

Note

Checks are the right place for “does this host have the tool I call?” verification. They are not the right place for fetching data or running tests — a 5-second budget and load-time execution make them a smoke test, not a full verifier.

Common pattern

Use them as a pair: dependencies prepares the environment, checks verifies it worked.

dependencies:
  scripts:
    - scripts/install_pd_tools.sh

checks:
  - name: subfinder
    command: command -v subfinder >/dev/null 2>&1
  - name: httpx
    command: command -v httpx >/dev/null 2>&1
  - name: nuclei
    command: command -v nuclei >/dev/null 2>&1

When a capability ships local orchestration around third-party binaries, this pattern makes failures visible before the agent tries to call a missing tool.

Inspecting results

The TUI capability manager lists check names with pass/fail state on each capability’s detail panel. From a worker, client.fetch_runtime_info() returns the same health list for programmatic monitoring.