Manifest-Driven Container Tool

Overview

The container-backed pattern, generalised. KaliToolbox is one hand-coded reference; ManifestToolFactory is what lets any image be its own typed library of named, parameterised actions an agent can call.

How it works

ManifestImageReader extracts the manifest via docker inspect (LABEL transport, no container start required), falling back to /etc/swarmai/manifest.json via a one-shot docker run cat. ManifestToolFactory.toTools(manifest) returns one ContainerBackedBaseTool per declared capability, each with its own JSON Schema (auto-derived from the manifest's parameter list), output parser, and resource policy. ManifestSmokeValidator runs every declared tool against safe synthetic inputs and rejects ones that don't actually behave as declared.

Example

When a user asks:

Audit my home network using whatever tools the framework can build for the gap.

the agent calls the tool:

// run.sh codex-skill-creation --dynamic-audit 192.168.1.0/24

and gets back: 1/6 build self-describing image 2/6 read manifest from LABEL: swarmai-mini-toolbox v1, 2 capabilities 3/6 materialise 2 tools: [nmap_scan, http_check] 4/6 smoke validate: 2/2 pass 5/6 hot-register with Agent 6/6 reactive audit complete in 21126 ms (9 container calls)

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

swarmai.skill.container.approval-gate optional

ImageApprovalGate consulted before every new image build/pull. Default AutoApprovalGate; production should opt into ConsoleApprovalGate or RememberingApprovalGate.

swarmai.skill.container.policy optional

ContainerPolicy enforcing allowed base images, banned Dockerfile patterns, max timeouts.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# Inline a manifest as base64 LABEL in your Dockerfile:
#   LABEL swarmai.manifest="<base64 of capability manifest JSON>"
#
# Schema for the manifest (decoded):
# {
#   "name": "my-toolbox",
#   "version": "1",
#   "tools": [
#     {
#       "name": "snake_case_tool",
#       "description": "What this tool does",
#       "triggerWhen": "When to pick this tool",
#       "parameters": [{"name": "target", "required": true}],
#       "entrypoint": "my-tool --target $TARGET",
#       "timeoutSeconds": 60,
#       "network": "bridge"
#     }
#   ]
# }

Java

import ai.intelliswarm.swarmai.skill.runtime.*;
import ai.intelliswarm.swarmai.tool.base.BaseTool;
import java.util.List;

ContainerSkillRuntime runtime = new ContainerSkillRuntime();

// Build (or pull) an image whose LABEL carries the capability manifest.
String tag = runtime.buildImage(myDockerfile, java.util.Map.of(
    ManifestImageReader.MANIFEST_LABEL, base64EncodedManifestJson));

// Read the manifest back, materialise BaseTools, smoke-validate, register.
CapabilityManifest manifest = new ManifestImageReader().read(tag).orElseThrow();
ManifestToolFactory factory = ManifestToolFactory.builder()
    .runtime(runtime).image(tag).build();
List<BaseTool> tools = factory.toTools(manifest);

var smokeResults = new ManifestSmokeValidator(runtime, factory)
    .validate(manifest, java.util.Map.of());

agent.registerTools(tools);   // hot-add to a running Agent

What it's good for

Real scenarios where agents put this tool to work.

Codex generates a new Dockerfile + manifest for a capability gap; framework smoke-validates and the agent uses the new tool the same conversation

Distributed teams ship containerised tool libraries that anyone can introspect via docker inspect

Reproducible audits: an image SHA + manifest LABEL is a portable, auditable capability bundle

Source

Implementation lives at swarmai-core/src/main/java/ai/intelliswarm/swarmai/skill/runtime/ManifestToolFactory.java in the swarm-ai repository.

Open manifest_driven_tool on GitHub →