Dependencies & Checks

Some capabilities need packages, system tools, or setup scripts before they work. Declare those under dependencies: and the sandbox runtime installs them after the capability syncs and before its components register. 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	uv pip install (falls back to pip)	Python packages the capability imports
packages	sudo apt-get update && sudo apt-get install -y	System packages (Debian-based sandboxes)
scripts	bash	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

The runtime installs in a fixed order: packages → python → scripts. On the default non-root sandbox image, the package step refreshes apt indexes with sudo apt-get update before sudo apt-get install -y. Scripts run in declaration order with the capability root as their working directory. Non-zero exit codes fail the install for that capability.

When multiple capabilities are bound to the same runtime, python deps are unioned across all of them and installed in a single uv pip install call — version conflicts surface immediately as a resolver error.

When the runtime re-runs installs

A successful pass marks the capability with an internal .dreadnode-installed file inside its sync cache, so subsequent boots skip packages and scripts for capabilities that haven’t changed. When you publish a new version of the capability, the sync replaces the cache directory and the install runs fresh on the next boot — you don’t need to bump or clear anything yourself.

python deps re-install on every boot so the venv re-resolves whenever the binding set changes. pip and uv pip are fast no-ops when nothing is missing.

When installs fail

Install failures log on the runtime but do not block the capability from loading — the loader will still register its components, and any preflight checks: you’ve declared run afterward. That’s the loud, user-visible signal: when a check goes red, look at the runtime logs for the install error, then fix the manifest or the host environment and reload.

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 runs with the capability root as its working directory, so relative paths like scripts/foo.py or tools/probe.sh resolve against the installed capability.

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.