Handbook
Packaging agents
The packaging package (packages/packaging/) builds deployable agent images from agent.package.v1 manifests and Dockerfile templates. New channel agents plug into Fleet without forking the Fleet repo.
Updated
Autonomy ceiling: A1_supervised — build tooling only; production deploy requires human gate.
agent.package.v1 manifest
Each agent ships a manifest (YAML or JSON) with schema discriminator forge.agent.package.v1:
| Field | Required | Description |
|---|---|---|
schema |
yes | forge.agent.package.v1 |
agent_id |
yes | Catalog id (communication, cursor_bridge, …) |
version |
yes | Semver for the package build |
entrypoint |
yes | Container command or module (python -m forge_communication.matrix.bot) |
dockerfile_template |
yes | Template name under docker/templates/ |
fleet_template |
yes | Fleet requirement_templates / docker_argv stub id |
env_refs |
no | Secret/env file keys (Matrix, NATS, KB path) |
health_check |
no | HTTP or exec probe for container-service |
matrix |
no | Bot user prefix, default rooms |
Manifest validation: src/forge_packaging/manifest.py.
CLI
forge-agents package build --agent communication
forge-agents package build --agent cursor_bridge --tag dev
Output: Docker image tagged for Granite registry + generated Fleet template fragment.
Dockerfile templates
Templates live under packages/packaging/docker/templates/:
| Template | Agent | Notes |
|---|---|---|
communication.Dockerfile |
communication |
KB index baked or mounted volume |
cursor_bridge.Dockerfile |
cursor_bridge |
Cursor CLI optional; documents laptop fallback |
Templates target existing Fleet docker_argv and container-services — no second execution plane.
Fleet requirement_templates stubs
Packaging emits stubs so Fleet jobs reference consistent argv shapes:
{
"template_id": "forge_agents_communication",
"docker_image": "forge-agents-communication:latest",
"argv": ["python", "-m", "forge_communication.matrix.bot"]
}
Orchestrator start/stop uses these stubs when registering container-services.
Stub agents (not full runtimes)
Hermes, OpenClaw, and Factory Droid packaging entries are stubs only in the A07 track — manifest + template skeleton without runnable images. Full runtimes remain separate workcell programs.