YggdraSIM

Run in Docker

Run a YggdraSIM operator shell inside a container, keep mutable runtime state on the host, and understand the limits of containerized card access.

On this page

Prerequisites

Docker engine available on the host
network access for the build-time dependency installs
a writable host directory for the persisted runtime tree

Steps

Build the image.
```
docker build -t yggdrasim .
```
Run the umbrella shell.
```
docker run --rm -it yggdrasim
```

Run a specific installed command.

docker run --rm -it yggdrasim yggdrasim-profile-package --cmd "STATUS; EXIT"

Mount a persistent runtime directory from the host.
```
docker run --rm -it \
  -v "$(pwd)/YggdraSIM-data:/opt/YggdraSIM-data" \
  yggdrasim yggdrasim-scp11-live --cmd "HELP; EXIT"
```
On first launch inside the container, the writable runtime tree lands in /opt/YggdraSIM-data, which is also the host directory. Subsequent runs reuse the same state.

Where containers shine

offline analysis and decode
simulator flows that do not require physical card hardware
CI smoke paths
documentation builds

Where containers do not help

real PC/SC reader access. Container USB passthrough is host-specific and can be fragile. For real card flows, run the launcher directly on the host.
HIL bridge work. SIMtrace2 access depends on host USB and permission setup.

Pitfalls

Without a volume mount the runtime tree lives inside the container. It goes away when the container is removed. Always mount a host directory when state persistence matters.
Be cautious with secrets. Keys and certificates under a mounted YggdraSIM-data/ are readable to processes inside the container.