Quickstart

Scaffold a capability, add one tool and one agent, install it into your local runtime, and drive it from the TUI.

Prerequisites

• The Dreadnode CLI authenticated (dn login)
• Python 3.11+
• An API key configured — see Authentication

Scaffold the capability

dn capability init web-recon
cd web-recon

The scaffold creates capability.yaml and a starter agents/example.md. Add --with-skills or --with-mcp to scaffold those folders too. Tools live under tools/ — create the directory yourself when you write the first one.

Write a tool

Create tools/lookup.py:

import typing as t

from dreadnode import tool


@tool
def lookup_host(
    host: t.Annotated[str, "Hostname or IP to look up"],
) -> dict[str, str]:
    """Resolve a host and return basic metadata."""
    return {"host": host, "status": "reachable", "source": "stub"}

Type hints become the tool schema the model sees. typing.Annotated supplies the parameter description.

Write an agent

Create agents/recon.md:

---
name: recon
description: Investigate a host and summarize what you found.
model: anthropic/claude-sonnet-4-5-20250929
tools:
  '*': false
  lookup_host: true
---

You are a reconnaissance agent. Use `lookup_host` to investigate any host the user mentions and summarize the result in two sentences.

The '*': false line opts the agent out of every runtime tool by default. lookup_host: true enables the one you just wrote.

Confirm the manifest

Open capability.yaml and make sure it looks like this:

schema: 1
name: web-recon
version: 0.1.0
description: Basic host reconnaissance capability.

You don’t need to list agents: or tools: — the loader auto-discovers both when the keys are omitted.

Install locally

From the parent directory:

dn capability install ./web-recon

install validates the manifest and symlinks the directory into your local store at ~/.dreadnode/capabilities/. Edits to the source are live on the next runtime reload.

Drive it from the TUI

dn

Press Ctrl+P, open the Installed tab, and enable web-recon. Start a new session with /agent recon, then send a prompt like Look up example.com. The agent calls lookup_host and returns the stubbed result.

Next steps

• Swap the stub tool body for a real implementation — Tools
• Add an MCP server for anything that isn’t pure Python — MCP servers
• Add a background worker to stream results out of the runtime — Workers
• Publish the capability so your team can install it — Publishing