Skip to content
YggdraSIM

Getting Started

Install YggdraSIM, verify prerequisites, and launch your first operator shell.

On this page

Prerequisites

  • Python 3.10 or newer
  • a PC/SC-compatible smart-card reader for card-facing flows
  • optional gpg when encrypted inventory payloads are enabled
  • optional Wireshark, osmo-remsim-client-st2, and SIMtrace2 for HIL work
  • optional Tools.CardBridge + SSH tunnel when the card reader is on a different host than the YggdraSIM process
  • optional on-disk pysim/ checkout when you need SAIP ASN.1 compile or the SCP11 local / eIM-local flows (see the Optional pySim checkout section below)

Install the runtime

Install the Python dependencies:

python -m pip install -r requirements.txt
python -m pip install -e .

The editable install makes the package entry points work from any directory that uses the same environment.

If your host exposes python3 instead of python, substitute python3 in the commands on this page.

Install the documentation tooling

python -m pip install -r requirements-docs.txt

Build or serve the site:

mkdocs serve
mkdocs build

The MkDocs configuration lives in mkdocs.yml, and the authored site pages live in site-docs/.

Launch the main menu

python main/main.py
python main/main.py --debug
python main/main.py --card-backend sim --sim-eim-identity /path/to/card_side_eim_identity.json
python main/main.py --gui
python main/main.py --web-server --host 127.0.0.1 --port 8765

Use --debug or --verbose on the wrapper when debug output should become the global default for launched modules. Use --gui for the desktop Universal GUI Command Center (requires the [gui] extra) or --web-server for the FastAPI loopback variant (requires the [gui-server] extra).

Launch the GUI safely

python -m pip install -e '.[gui]'
python main/main.py --gui

For a remote lab server, keep the bind on loopback and tunnel it:

python -m pip install -e '.[gui-server]'
python main/main.py --web-server \
  --host 127.0.0.1 \
  --port 8765 \
  --token-file ~/.config/yggdrasim/gui.token

ssh -fN -L 8765:127.0.0.1:8765 user@lab-host

See Universal GUI Command Center for the token, APDU stream, remote-card, and host-shell posture.

Direct module entry points

After python -m pip install -e ., these module forms can be run from any directory in the same environment:

python -m SCP03
python -m SCP80
python -m SCP11
python -m SCP11.live
python -m SCP11.relay
python -m SCP11.local_access
python -m SCP11.eim_local
python -m Tools.HilBridge.main
python -m Tools.HilBridge.supervisor
python -m Tools.ProfilePackage
python -m Tools.ApduFuzz
python -m Tools.EumDiag
python -m Tools.SuciTool

Installed command equivalents:

yggdrasim-scp03
yggdrasim-scp80
yggdrasim-scp11
yggdrasim-scp11-live
yggdrasim-scp11-relay
yggdrasim-scp11-local-access
yggdrasim-scp11-eim-local
yggdrasim-hil-bridge
yggdrasim-hil-supervisor
yggdrasim-profile-package
yggdrasim-profile-autoload
yggdrasim-apdu-fuzzer
yggdrasim-eum-diag
yggdrasim-suci-tool

Simulator note

  • --sim-eim-identity selects the simulated card's default BF55 eIM identity file
  • Workspace/LocalEIM/eim_identity.json remains the Local eIM shell identity
  • Workspace/SIMCARD/eim_identity.json remains the simulator-side default when no stronger card-side override is applied

pySim provisioning

YggdraSIM treats pySim as an upstream dependency rather than a vendored copy. The canonical distribution channel is the [saip] extra, which installs upstream pySim directly from its GitHub mirror:

python -m pip install -e '.[saip]'

That one command unlocks the SAIP ASN.1 compile path used by Tools.ProfilePackage, the SAIP transcode TUI, the profile-scaffold wizards, and the SCP11 local / eIM-local flows. A bare pip install -e . without the extra still works for the flows that do not touch SAIP; yggdrasim --doctor reports pySim: WARN (non-fatal) and SAIP-dependent tests auto-skip via tests/conftest.py.

Developer checkout (advanced)

If you want to iterate against an unreleased upstream branch, drop a checkout at <repo>/pysim:

git clone https://github.com/osmocom/pysim.git pysim

The pysim/ directory is listed in .gitignore and is never redistributed with this project. When present, it takes priority over the installed wheel so your edits show up immediately. The same principle applies to pyscard and every other third-party Python dependency: installed from the normal packaging channels, not vendored.