Introduction

Hovel is a Go-hosted framework for authorized red-team emulation, controlled lab exercises, defensive validation, and operator workflow automation.

Hovel is a platform for wrapping and operating third-party proofs of concept, not a catalog of first-party exploits. The project provides the engine, SDKs, descriptors, providers, guardrails, examples, installed-payload inventory, and operator experience that make third-party modules acceptable to run and inspect.

The main product goal is straightforward:

Make modules easy to write, keep long-lived capabilities managed by the engine, and give operators a clear view of every throw, installed payload, and session.

The central runtime is a local engine, hoveld, which owns operations, chains, throws, module processes, provider-backed payload state, installed payload inventory, sessions, structured events, artifacts, and workspace storage. Interactive cli mode, one-shot chain-file execution, and the MCP agent front end are implemented clients over the same application services through the stable daemon RPC contract. hovel tui is an explicit not-implemented role; a public REST/OpenAPI adapter, a general managed-service process runtime, and richer MCP resources and prompts remain future work over the same boundary.

How Hovel Is Shaped

1. The host is written in Go.
2. Python is the first-class module authoring language.
3. hoveld is mandatory; invoking hovel starts or attaches to a daemon.
4. Modules run as bounded processes through normal module runtime contracts.
5. Long-lived capabilities are represented in the target model; the current source validates service descriptors but does not launch general service processes.
6. Providers expose typed resources such as payloads, artifacts, facts, credentials, listeners, and sessions. The current implemented provider path is module RPC, especially Go payload-provider modules.
7. Payload providers return tagged bytes with minimal framework validation, and return explicit installed-payload descriptors when they install or reconnect target-side payloads.
8. Hovel core owns installed-payload persistence in SQLite; providers own reconnect and cleanup semantics.
9. Throws emit structured events onto a shared logging rail consumed by every front end and persistence sink.
10. The implementation is local-first: one workspace, one local daemon, explicit module installation, and Task-backed development workflows.

Product Shape

Hovel exposes one engine through multiple front ends. In the current source, CLI, one-shot execution, daemon management, and the MCP agent adapter are implemented. MCP can inspect catalog and workspace state, apply chain state, start guarded throws, list installed payloads, and call provider-owned payload commands. hovel tui is an explicit not-implemented role, while REST/OpenAPI and richer MCP resources and prompts remain future work:

All front ends must call the same application services. As adapters evolve, the TUI must not contain business logic, the MCP adapter must not bypass validation, and the REST API must not become a second framework. One-shot execution and cli mode must not implement their own chain runners.

Current Product Boundary

Hovel is intentionally local-first. The current product boundary excludes:

1. Distributed team-server architecture.
2. Persistent multi-user RBAC.
3. Public module marketplace semantics.
4. Automatic stealth guarantees.
5. Browser UI.
6. Mandatory container isolation.
7. First-party exploit or payload corpus.

The current source is organized around a narrow, reviewable loop:

1. Initialize a local workspace.
2. Start or attach to hoveld from hovel.
3. Load trusted modules from the configured module catalog and validate their handshake and schema.
4. Launch Python, Go, or Rust modules through the shared stdio JSON-RPC contract.
5. Complete handshake, execution, logging, session handling, and shutdown.
6. Emit structured events through the shared logging rail.
7. Persist the throw plan, confirmation record, event records, artifacts, any explicit installed-payload records, and replayable throw record.
8. Inspect throws, artifacts, payload inventory, and sessions from CLI or MCP where supported.
9. Save and load targetless chain templates and configured chain YAML files for reuse and one-shot execution.

Future work should attach to this loop instead of creating parallel execution paths. That includes the TUI, REST/OpenAPI, general managed services, richer chain editing, and richer MCP resources and prompts.

Open Product Questions

These decisions remain open because they affect operator workflow, deployment shape, or compatibility:

1. Whether chains are only declarative YAML or also authorable in Python or Go.
2. Whether REST ships before or after the TUI.
3. Whether service processes and module processes share one protocol.
4. Whether reusable payload configuration profiles need first-class persistence beyond installed payload records.
5. Which isolation mechanisms are required beyond process supervision and Python dependency isolation.