OCI Container Runtime Inspector — inspect, validate, and diff OCI bundles with zero dependencies on container daemons.
OciSpy reads config.json directly from OCI bundles and gives you rich, structured output about process configuration, namespaces, mounts, capabilities, hooks, resource limits, and annotations — all without needing a running container runtime.
- Full OCI bundle inspection in a single command
- Process configuration: entrypoint, env vars, UID/GID, rlimits
- Linux namespace enumeration with new vs shared status
- Mount point table with type, source, and options
- Capability set display (bounding, effective, permitted, inheritable, ambient)
- Lifecycle hook inspection (prestart, poststart, poststop, etc.)
- Linux resource limits: memory, CPU, pids
- Annotation and label listing
- OCI spec validation with errors and warnings
- Config diff between two bundles side by side
- Export to JSON, YAML, or plain text
- Colored terminal output with
--no-coloroverride
| Command | Description |
|---|---|
ocispy inspect |
Full inspection of an OCI bundle |
ocispy spec |
Show parsed OCI spec overview |
ocispy process |
Show process configuration |
ocispy namespaces |
Show namespace configuration |
ocispy mounts |
Show mount points |
ocispy caps |
Show capability sets |
ocispy annotations |
Show annotations and labels |
ocispy hooks |
Show lifecycle hooks |
ocispy resources |
Show resource limits |
ocispy validate |
Validate OCI bundle config against spec |
ocispy diff |
Diff two OCI bundle configs |
ocispy export |
Export parsed OCI config to JSON/YAML/text |
ocispy version |
Show version information |
The OCI (Open Container Initiative) Runtime Specification defines how container runtimes like runc, crun, and kata-containers should create and manage containers. An OCI bundle is a directory containing a config.json (the container specification) and a rootfs/ directory (the container filesystem). OciSpy reads and inspects that config.json without needing a container daemon.
| Component | Library |
|---|---|
| CLI framework | github.com/spf13/cobra |
| Configuration | github.com/spf13/viper |
| Table output | github.com/olekukonko/tablewriter |
| Color output | github.com/fatih/color |
| YAML export | gopkg.in/yaml.v3 |
| JSON parsing | encoding/json (stdlib) |
The CLI layer (cmd/) handles flag parsing and delegates to pkg/bundle for loading. The bundle loader reads config.json via pkg/spec, deserializing into internal/models. Inspectors, validators, exporters, and the differ all operate on those models and write output through pkg/output.
docker inspect requires a running Docker daemon and a container ID. OciSpy works directly on OCI bundle directories — no daemon, no container ID, no network call. It works on any OCI-compliant bundle regardless of which runtime will execute it.
go install github.com/mdryaan/ocispy@latestOr build from source:
git clone https://github.com/mdryaan/ocispy
cd ocispy
go build -o ocispy ./...ocispy inspect --bundle /path/to/bundle
ocispy validate --bundle /path/to/bundle
ocispy spec --bundle /path/to/bundle
ocispy process --bundle /path/to/bundle
ocispy namespaces --bundle /path/to/bundle
ocispy mounts --bundle /path/to/bundle
ocispy caps --bundle /path/to/bundle
ocispy annotations --bundle /path/to/bundle
ocispy hooks --bundle /path/to/bundle
ocispy resources --bundle /path/to/bundle
ocispy diff --bundle1 /path/to/bundle1 --bundle2 /path/to/bundle2
ocispy export --bundle /path/to/bundle --format yaml
ocispy export --bundle /path/to/bundle --format json- Go 1.21 or later
- An OCI bundle directory containing a valid
config.json
See CONTRIBUTING.md for development setup, how to add new inspectors and exporters, and code style rules.
MIT — see LICENSE.