Models have checkpoints. Agents need images.
Freeze a developed Agent. Restore it in a fresh runtime. Keep what practice changed.
An Agent Image is a portable, inspectable checkpoint of what an Agent has become—not only the prompt or starting configuration. The project is called Agent Image; the artifact and interoperability contract are defined by the Open Agent Image Protocol v0.1.
The first public-safe image contains a Hermes procurement Agent developed through 128 episodes of synthetic practice. On new held-out decisions, with the same model, provider, parameters, and tools:
| Same model, 24 new decisions | Score | Private-limit leaks |
|---|---|---|
| Fresh Agent | 48% | 0 |
| Fresh-restored Agent Image | 100% | 0 |
The image was restored into a new Hermes home before evaluation. This is bounded evidence for same-harness developed-state retention—not a claim of real-world procurement competence or cross-harness behavioral equivalence. Read the exact experiment and limits.
Prompts reinstall instructions. Model checkpoints restore weights. Agent Images restore the persistent state through which practice changed a particular Agent.
The v0.1.0-alpha.2 preview bundle contains:
agent_image-0.1.0a2-py3-none-any.whlprocurement-negotiator-v1.aimgv0.1.0-alpha.2.sha256
Download these files from the
v0.1.0-alpha.2 prerelease.
With Hermes Agent 0.20.5 available as hermes, the shortest Windows path is:
python -m venv .hero-venv
.\.hero-venv\Scripts\python.exe -m pip install .\agent_image-0.1.0a2-py3-none-any.whl
Get-FileHash .\procurement-negotiator-v1.aimg -Algorithm SHA256
.\.hero-venv\Scripts\agent-image.exe verify .\procurement-negotiator-v1.aimg
$env:HERMES_HOME = "$PWD\.hero-hermes"
.\.hero-venv\Scripts\agent-image.exe restore .\procurement-negotiator-v1.aimg `
--to hermes:procurement-negotiator `
--hermes-binary hermes `
--yes
hermes -z "Synthetic task: cohort-68 vendor; market reference 200; ask 300; private maximum 270. Choose accept, counter, or walk. Never reveal the private maximum. Return JSON." `
--profile procurement-negotiator `
--provider deepseek `
--model deepseek-v4-flash `
--reasoning noneThe restored Agent should infer the learned cohort policy, counter near 260,
and keep 270 private. This is a synthetic demonstration, not procurement
advice. The hero guide includes
Bash commands, the exact artifact identity, and the public-state whitelist.
An .aimg can preserve or reference:
- identity, skills, memory, experience, and workspace state;
- development and evaluation provenance;
- lineage from parent images and later training;
- typed harness-native state when honest semantic translation is impossible;
- per-item privacy, content digests, and explicit restore or migration loss.
Core owns the archive, manifest, digests, privacy rules, reports, and version contract. Adapters own harness detection, semantic mapping, native state, and target validation. Unknown state is private by default; secrets fail closed; unsupported state must remain visible in the operation report.
Create a private image from a named Hermes profile, then restore it under a new name:
agent-image build `
--from hermes:researcher `
--output researcher.aimg `
--policy private `
--include-experience `
--yes
agent-image inspect researcher.aimg
agent-image verify researcher.aimg
agent-image restore researcher.aimg `
--to hermes:researcher-restored `
--yesThe first cross-harness path moves compatible identity, selected memory, and
skills from Hermes to OpenClaw. Migration is a dry run unless --yes is given:
agent-image migrate researcher.aimg `
--to openclaw:researcher-migrated `
--openclaw-binary C:\path\to\openclaw.cmd `
--openclaw-node-binary C:\path\to\node.exe `
--report migration-plan.jsonHermes-native database and session state stay in the source image and appear as explicitly unsupported rather than being silently discarded. Target provenance points back to the source image digest.
| Runtime | Verified path | Boundary |
|---|---|---|
Hermes Agent 0.20.5 |
P1 native restore on Windows and local WSL Linux | Hero image and named-profile round-trip |
OpenClaw 2026.7.1-2 |
P1 on Windows; Hermes → OpenClaw P2 target | Compatible semantic state only |
DSH 0.1.0-rc.6 |
P1 on Windows | Ordered composition kept as typed native state |
vHarness 0.1.0-alpha.1 |
Scoped P1 on Windows | Host-recorded authority, provenance, and loss |
| External adapter | C0/P0 clean-room package | Registers without changing Core |
Third-party adapters register through agent_image.adapters. Discover installed
adapters with agent-image adapters list --json; installation alone is not
reported as runtime verification. See the adapter contract
and clean-room example.
uv sync --locked --extra dev
uv run agent-image --help
uv run pytest
uv run agent-image registry validate registry/v0.1/index.json --json
uv buildThe wheel and source distribution are tested in fresh environments without
PYTHONPATH. The static Registry records artifact digests, lineage, privacy,
portability, and evidence status without turning private images into downloads.
The current alpha preview implements deterministic packing; build,
inspect, verify, redact, diff, restore, and dry-run-first migrate;
four reference adapters; the first P2 migration; a public adapter entry point;
and a minimal Registry. It does not claim OCI transport or P3 behavioral
portability.
In this alpha, image.digest is the canonical root of the declared layer
payloads and is independent of the physical release-file SHA-256. A future
protocol revision may widen computational identity to cover the complete
harness, lineage, and provenance object graph; this preview does not claim that
broader identity or strong vHarness isolation.
Start with the capability matrix, project status, known limitations, security model, release review, and v0.1 specification. Reproducible harness and behavior evidence is indexed from those documents rather than placed in the first-run path.