Images and Builds

A3S Box works with Linux OCI images. The local image store is shared by pull, run, build, load, save, tag, and image-inspect.

References and Cache Resolution

Examples:

Docker Hub aliases resolve to the same cached image when unambiguous.

Pull and Auth

a3s-box login ghcr.io -u USER -p TOKEN
a3s-box pull ghcr.io/org/app:v1
a3s-box logout ghcr.io

Credentials are stored in the A3S home directory. Registry operations require network access and are intentionally separated from pure unit tests.

Signature Verification

# Cosign public-key verification
a3s-box pull --verify-key cosign.pub ghcr.io/org/app:v1

# Cosign keyless verification
a3s-box pull \
  --verify-issuer https://accounts.google.com \
  --verify-identity user@example.com \
  ghcr.io/org/app:v1

Keyless verification needs registry and Sigstore/Fulcio/Rekor-related network access. Offline tests cover parser and payload pieces; end-to-end verification must run in a network-enabled environment.

Inspect, Save, Load, Tag

a3s-box images
a3s-box image-inspect alpine:latest
a3s-box history alpine:latest
a3s-box tag alpine:latest local/alpine:test
a3s-box save -o alpine.tar alpine:latest
a3s-box load -i alpine.tar --tag local/alpine:test
a3s-box rmi local/alpine:test

image-inspect includes image config such as entrypoint, cmd, env, workdir, user, exposed ports, volumes, labels, stop signal, healthcheck, and ONBUILD metadata when present.

Build Subset

a3s-box build -t app:dev .
a3s-box build -t app:dev -f Containerfile .
a3s-box build -t app:dev --build-arg VERSION=1.2.3 --platform linux/amd64 .

Supported Dockerfile instructions:

• FROM, including scratch;
• shell-form RUN;
• shell-form COPY and ADD;
• WORKDIR, ENV, ENTRYPOINT, CMD, EXPOSE, LABEL, USER, ARG, SHELL, STOPSIGNAL, HEALTHCHECK, ONBUILD metadata triggers, and VOLUME.

Important boundaries:

• RUN uses isolated Linux chroot and requires root-capable Linux.
• macOS rejects RUN by default. Set A3S_BOX_UNSAFE_HOST_RUN=1 only for local unsafe experiments.
• Unsupported flags, for example COPY --chown and ADD --chown, fail explicitly.
• --platform accepts one target platform. Multi-platform indexes are not implemented.
• This is not a buildx replacement.

Push

a3s-box tag app:dev registry.example/org/app:dev
a3s-box push registry.example/org/app:dev

Push uses the OCI registry path and requires a reachable registry. Signing after push is supported through the CLI --sign-key path where configured.