// field manual
Hovel Book
A practical guide to operating the local engine, understanding the platform, writing modules, applying the safety model, and validating the repository.
// 06 parts · 30 chapters
Contents
Read front to back, or enter at the part closest to the work in front of you.
Foundations
5 chapters- 01 User Guide This guide is the shortest path from a clean install to an operator-visible Hovel workflow. It covers local workspaces, config layering, module installation, the managed daemon, interactive cli mode, one-shot…
- 02 Introduction Hovel is a Go-hosted framework for authorized red-team emulation, controlled lab exercises, defensive validation, and operator workflow automation.
- 03 Safety and Scope Hovel is intended for authorized security testing, adversary emulation, internal lab research, CTF-style training, defensive validation, and controlled red-team development.
- 04 Architecture Hovel uses a clean application core with adapters at the edges.
- 05 Domain Model A workspace is the local project/database context for operations, targets, throws, modules, services, structured events, artifacts, installed payload inventory, and provider state.
Runtime Platform
6 chapters- 06 Modules and Services Modules and services are separate domain concepts with separate lifecycle expectations.
- 07 TLS & PKI How Hovel owns TLS certificate custody, trust, assignment, revocation, provider delivery, and hybrid post-quantum key establishment.
- 08 Providers, PKI, Artifacts How Hovel separates provider contracts, encrypted PKI custody, credential delivery, artifacts, sessions, and durable audit evidence.
- 09 Squatter Payload Provider Squatter is Hovel's first core payload provider. It is a lab and demonstration payload system for authorized environments. The provider is a normal Hovel payload_provider module that speaks JSON-RPC over stdio; the…
- 10 Mesh Provider-owned node operations, listening posts, routed streams, local bridges, and assignment-bound TLS credentials.
- 11 Operations, Chains, Throws Operations are the durable work context. Chains are workflows with typed steps inside an operation. Throws are replay-inspectable executions of a chain against targets.
Operator Experience
5 chapters- 12 Operator Workflows The operation is the root object of operator work. A chain is the throw path inside that operation: it is the shared workspace where clients collaborate, add modules, validate readiness, and throw against…
- 13 TLS Operations Operator runbook for workspace PKI initialization, certificate and trust lifecycle, Mesh assignments, revocation, and recovery boundaries.
- 14 Front Ends Front ends are adapters over application services. They must share validation, planning, execution, structured logging rail subscriptions, scope guardrails, and audit behavior.
- 15 UI Components The UI catalog captures terminal components that are shared by command output, demo tapes, and future richer front ends. Each component is rendered from the same Go code used by the development catalog binary.
- 16 MCP and Agent Operation hovel mcp is the agent-facing front end for Hovel. The current source-backed slice is an MCP server with stdio by default, optional streamable HTTP, typed catalog/workspace/chain tools, installed-payload tools,…
Module Development
8 chapters- 17 Overview A module is a self-contained unit of offensive capability — a survey that gathers facts, an exploit that acts on a target, or a payload provider that builds something to deliver. Modules are not compiled into the…
- 18 Mesh Development Implement Mesh providers, listening posts, routed sessions, bridges, and assignment-bound TLS credential delivery.
- 19 Credential Providers Build optional credential delivery, encoding, and stamping providers with exact Go, Python, Rust, daemon, and Mesh contracts.
- 20 Wire Protocol This is the contract between the Hovel daemon and a module process. The SDKs implement it for you; you only need this page if you are writing an SDK, debugging a module by hand, or porting Hovel modules to a new…
- 21 Python Modules Python is the quickest way to write a Hovel module: there is no build step, and the daemon launches it straight from source through the interpreter. The SDK lives at sdk/python/hovel_sdk ; the worked examples are…
- 22 Go Modules A Go module compiles to a single static binary that the daemon launches by path. The SDK is dependency-light and lives at sdk/go/hovel ( github.com/vibepwners/hovel/sdk/go/hovel ); the worked examples are under…
- 23 Rust Modules A Rust module compiles to a single binary that the daemon launches by path. The SDK lives at sdk/rust/hovel and is dependency-free : it hand-rolls a tiny JSON layer and base64 codec rather than pulling in serde_json…
- 24 Case Study: MS17-010 The mock modules elsewhere in these guides show the shape of the SDK without touching a real target. This page documents a pair of real modules — ms17-010-survey and ms17-010-exploit — that fingerprint and exploit…
Engineering
3 chapters- 25 Configuration & Distribution Hovel is distributed as a Python-installed Go binary, with modules distributed separately as trusted .tgz packages. Configuration is explicit, schema-validated, offline-ready, and layered in a fixed order.
- 26 Testing Strategy Hovel tests contracts first. The main risk is not only that a function breaks; it is that CLI, one-shot execution, MCP, daemon RPC, module hosts, storage, and SDKs disagree about the same operation, chain, throw,…
- 27 Development Guide Hovel is developed as a monorepo with a sparse-checkout friendly layout. The core framework lives in its own build workspace, while SDKs, modules, and documentation live beside it. The root task system is the…
Reference
3 chapters- 28 Daemon RPC The RPC boundary between hoveld and Hovel front ends is a stable v1 contract. It is used by interactive cli , one-shot chain-file execution, hovel mcp , daemon management code, and future TUI or REST adapters that…
- 29 TLS & PKI API This guide is for authors of CLI, local web, Elixir, and other HTTP/JSON clients that control Hovel workspace PKI through hoveld . The machine-readable source of truth is the OpenAPI 3.1 contract ; the transport and…
- 30 Descriptors & Schemas Descriptors are the stable boundary between authored content and the Hovel engine. They should be schema-validated and versioned from the beginning.