openspec

packaged by Chainguard

Chainguard Container for openspec

OpenSpec is a CLI from Fission AI for spec-driven development with AI coding assistants. It scaffolds a specification store in your repository, turns proposed work into structured change folders, validates specifications and their scenarios, and archives completed changes back into the living specification set.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/openspec:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Upstream OpenSpec is distributed as an npm package. It publishes no container image and no Dockerfile, so there is no upstream image for this one to be compatible with. The CLI itself is the same one an openspec npm installation provides, built from the OpenSpec source against a packaged Node runtime, but everything about how it is packaged as a container is defined by Chainguard. Those decisions are documented below so you can rely on them.

The image also carries the pieces the CLI shells out to: the Node runtime it executes under, git for openspec store setup, and a minimal shell so you can chain several OpenSpec commands in one container invocation.

openspec store setup commits with Git and records the new store under $XDG_DATA_HOME/openspec, falling back to $HOME/.local/share/openspec. That path is outside /workspace, so in a throwaway container the registration is lost when the container exits, and the commit fails unless Git has an identity. Set XDG_DATA_HOME to a mounted path and provide GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL (or git config values), or pass --no-init-git to skip the Git steps.

There is no openspec daemon or server. The image runs one command and exits, which makes it a good fit for a CI step or a Kubernetes Job.

OpenSpec prompts only when stdin is a terminal, so a docker run without -t is already non-interactive and needs no extra configuration. OPEN_SPEC_INTERACTIVE=0 matters when you do allocate a TTY and still want prompts suppressed. Archiving is the exception, because its confirmations are gated on --yes rather than on interactivity, so pass --yes to openspec archive in any unattended run.

Getting Started

OpenSpec works on a checkout of your project, so mount the repository at /workspace. Run it as your own user so the files it creates stay owned by you:

docker run --rm -v "$PWD:/workspace" --user "$(id -u):$(id -g)" \
  cgr.dev/ORGANIZATION/openspec:latest init --tools claude

This scaffolds the specification store and the instruction files for your coding assistant:

Config: openspec/config.yaml (schema: spec-driven)

Running init a second time on an initialized project, and running update, migrates OpenSpec's global configuration into $XDG_CONFIG_HOME/openspec, falling back to $HOME/.config/openspec. Docker sets HOME=/ for any --user UID that is not in the image's /etc/passwd, and / is not writable, so those runs fail with EACCES: permission denied, mkdir '/.config/openspec'. Point XDG_CONFIG_HOME at a writable path to avoid it.

Because every invocation needs the same mount, a shell function keeps the remaining examples readable:

openspec() {
  docker run --rm -i -v "$PWD:/workspace" --user "$(id -u):$(id -g)" \
    -e XDG_CONFIG_HOME=/tmp/openspec-config \
    cgr.dev/ORGANIZATION/openspec:latest "$@"
}

/tmp is world-writable in the image, so the global configuration lands somewhere every UID can write. It is discarded with the container; mount a directory there instead when you want it to persist across runs.

Start a change to describe work you are proposing:

openspec new change add-greeting --schema spec-driven

The change begins empty, and you or your coding assistant fill in its artifacts. new change creates only the change directory, so make the spec directory before writing a delta into it:

mkdir -p openspec/changes/add-greeting/specs/greeting
cat > openspec/changes/add-greeting/specs/greeting/spec.md <<'EOF'
## Purpose
Welcome users with a predictable message when they open the application.

## ADDED Requirements

### Requirement: Welcome message
The system SHALL display a welcome message when opened.

#### Scenario: Application opens
- **WHEN** a user opens the application
- **THEN** the application displays "Welcome"
EOF

Validate the change before handing it to a reviewer or an agent:

openspec validate add-greeting --type change --strict

Change 'add-greeting' is valid

Validation is the gate worth wiring into CI. It exits non-zero and explains the problem when a requirement is incomplete, for example when a requirement has no scenario:

✗ [ERROR] greeting/spec.md: ADDED "Welcome message" must include at least one scenario

Once the work is done, archiving folds the change's deltas into the project's living specifications and clears it from the active list:

openspec archive add-greeting --yes

Specs updated successfully.
Change 'add-greeting' archived as '2026-01-15-add-greeting'.

Add --json to list, show, validate, and status when a script or an agent needs to consume the result rather than read it.

Configuration

OpenSpec stores per-project configuration in openspec/config.yaml and reads a handful of environment variables at runtime. The ones that matter in a container are:

In Kubernetes, run OpenSpec as a Job with the project mounted at /workspace. The volume has to carry the repository, since validate --specs has nothing to check against an empty directory:

apiVersion: batch/v1
kind: Job
metadata:
  name: openspec-validate
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      securityContext:
        runAsNonRoot: true
      containers:
        - name: openspec
          image: cgr.dev/ORGANIZATION/openspec:latest
          args: ["validate", "--specs", "--strict"]
          env:
            - name: OPEN_SPEC_INTERACTIVE
              value: "0"
          volumeMounts:
            - name: workspace
              mountPath: /workspace
      volumes:
        - name: workspace
          persistentVolumeClaim:
            claimName: my-project

An emptyDir works too when a prior step populates it, and needs no fsGroup, because kubelet creates it world-writable.

Documentation and Resources

• OpenSpec repository
• Spec-driven development with OpenSpec

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.