base

The supply-chain-verified substrate agents run on.

Reference container image for agentd agent sessions. An autonomous agent's runtime is exactly the kind of binary that deserves paranoia, so this image earns trust the checkable way: a minimal, zero-CVE-target Wolfi OS layer; the runa runtime built from a pinned, immutable source ref; and the agent runtime installed only after its release manifest verifies against a pinned GPG fingerprint and the binary matches the manifest's sha256 — a build that fails closed on any mismatch. The Dockerfile documents every one of those decisions inline; it is the ecosystem's exemplar for self-documenting infrastructure.

base is the Run tier's substrate in the Tesserine stack (ecosystem map: commons SOURCE-OF-TRUTH.md).

What's Inside

OS layer: Wolfi — glibc-based, zero-CVE target, purpose-built for containers.

agentd contract: The runner expects the image to provide /bin/sh, git, ssh, useradd, gosu, and chown. These are installed as Wolfi packages. The runner enters through /bin/sh -lc with a generated script that creates an unprivileged user, clones the target repository, and drops privileges before executing the session command. The image sets no ENTRYPOINT or CMD — agentd owns the entrypoint.

Cognitive runtime: runa, built from source. Loads methodology manifests, validates artifacts, enforces dependency graphs.

Agent runtime: Claude Code, pinned to a verified Anthropic release binary. Authenticate headlessly by injecting ANTHROPIC_API_KEY as a credential in your agentd agent configuration.

Building

Deployment builds must pin source material to immutable refs: tags or full commit SHAs. Do not build deployment images from main; mutable branch refs can reuse stale container build layers while the remote branch has moved. The shared release-candidate convention is defined in commons RELEASE.md.

podman build \
  --build-arg BASE_REF=v0.1.1 \
  --build-arg RUNA_REF=v0.1.2 \
  -t tesserine/base:v0.1.1 .

For local development, the defaults are usable, but they intentionally label the base image ref as local:

podman build -t tesserine/base:local .

Inspect the image labels to confirm what was built:

podman inspect tesserine/base:v0.1.1 | jq '.[0].Config.Labels'

Claude Code is intentionally pinned in the Dockerfile. Version bumps are manual build-substrate changes so the release manifest signature, binary checksum, image build, and runtime contract can be verified together. The built image exposes org.tesserine.base.ref, org.tesserine.runa.ref, and org.tesserine.claude-code.version labels for deployment inspection.

Release operation is documented in RELEASING.md. The release tooling verifies the changelog, Dockerfile label surface, release workflows, and tag-time image identity before publishing GitHub releases.

Using with agentd

Reference this image in your agent configuration:

[[agents]]
name = "site-builder"
base_image = "localhost/tesserine/base"
methodology_dir = "../groundwork"
repo = "https://github.com/your-org/your-project.git"

[agents.command]
argv = ["claude", "-p", "--dangerously-skip-permissions"]

[[agents.credentials]]
name = "ANTHROPIC_API_KEY"
source = "AGENTD_ANTHROPIC_KEY"

Export the credential source in the daemon's environment before starting agentd:

export AGENTD_ANTHROPIC_KEY="sk-ant-..."
agentd daemon --config /etc/agentd/agentd.toml

Customizing

Fork this repo and modify the Dockerfile. Common customizations:

• Different agent runtime: Replace the Claude Code release binary with Codex (npm i -g @openai/codex), or any CLI that can receive prompts and produce file changes.
• Additional tools: Add language runtimes, linters, or build tools your agents need.
• Different methodology: The methodology is mounted read-only by agentd at runtime, not baked into the image. No image change needed to switch methodologies.

Contributing

The change loop for the image and its scripts:

1. Edit Dockerfile (preserve its self-documenting header and per-decision rationale comments — they are the contract) or the release scripts.

2. Verify locally:

   podman build --tag localhost/tesserine/base:dev .
   ./scripts/test-release-check          # release-check behavior
   ./scripts/verify-release-adoption.sh  # end-to-end ceremony self-test

3. Record the change in CHANGELOG.md under [Unreleased].

Version pins (RUNA_REF, CLAUDE_CODE_VERSION, the signing-key fingerprint) have their own procedures in RELEASING.md.

Container Contract

The agentd runner makes these assumptions about the image:

Requirement	Why	Provided by
/bin/sh	Entrypoint shell for the generated setup script	bash (via bash-binsh)
useradd	Creates the unprivileged session user	shadow
gosu	Drops root privileges permanently before session command	gosu
git	Clones the target repository into the workspace	git
ssh	Enables Git SSH clone and push transport	openssh-client
chown	Transfers home directory ownership to the session user	coreutils

If you build a custom image, these six capabilities must be present.

License

MIT