Credentials#

The launcher manages HuggingFace and NGC API tokens so they are never stored in source files or YAML configurations.

LiveKit credentials#

DeviceIOHub generates a random LiveKit API key and secret at startup when neither environment credential is set and both YAML values are missing or blank. Shipped hub YAML files leave both fields blank, so samples run without credential setup or a LiveKit account. The generated pair configures the local LiveKit server and token endpoint and changes on each restart. Clients use the connection token supplied by DeviceIOHub.

For a fixed pair, set LIVEKIT_API_KEY and LIVEKIT_API_SECRET in the launch environment, or supply api_key and api_secret in a private device_io_hub.yaml. If either environment variable is set, both must contain non-blank values; the environment pair replaces the YAML pair together. Partial pairs fail at startup, and blank environment values do not trigger credential generation. Never commit credentials.

Model credentials#

Tokens are cached in ~/.config/xr-ai/credentials.json — outside any project directory. Values already in os.environ always take priority (useful in CI or when you want to override the cache).

run_stack always calls load_credentials() before spawning child processes, so any token saved in the credentials file, exported in the environment, or stored by huggingface-cli login is injected into every subprocess in the stack automatically — no per-sample wiring needed.

HuggingFace token (HF_TOKEN)#

Required by default for the launchers that download model checkpoints (model_servers). The default models are public, but unauthenticated Hub downloads are rate-limited to the point of stalling indefinitely on multi-GB checkpoints (no error, no progress output), so the orchestrators refuse to start without a token rather than hang silently on first launch. A token is also required outright for:

  • Gated models — any model whose HuggingFace page requires accepting a license or requesting access (plus license acceptance on your account).

Pocket TTS first attempts to load voice-cloning weights from the gated kyutai/pocket-tts model. If access is unavailable, the upstream package automatically loads its ungated no-voice-cloning weights; the checked-in predefined voice works with either variant. Review the current acceptable-use terms before accepting gated access. The terms and artifact revisions reviewed for this release are recorded in the repository’s THIRD_PARTY_NOTICES.md.

The samples do not prompt for it. If HF_TOKEN is not set, the orchestrator prints an actionable error and exits; pass --allow-anonymous to start without a token anyway (all weights already cached, or you accept the stall risk). Provide the token any one of these ways; all are picked up automatically:

# 1. Environment variable (highest priority; good for CI and one-off overrides)
export HF_TOKEN=hf_xxx

# 2. huggingface-cli login (writes ~/.cache/huggingface/token)
huggingface-cli login

# 3. From the repository root, save it once for all samples (written to
#    ~/.config/xr-ai/credentials.json and ~/.cache/huggingface/token)
uv run --project utils/xr-ai-launcher python -c \
  "from xr_ai_launcher import ensure_credentials; ensure_credentials('HF_TOKEN')"

Get a token at https://huggingface.co/settings/tokens. HF_TOKEN is also written to ~/.cache/huggingface/token — the standard location huggingface_hub checks — so child processes (e.g. vlm-server) find it even when env-var inheritance is incomplete, and an existing huggingface-cli login is reused without any further setup.

NGC API key (NGC_API_KEY)#

Required for the NIM model backend and restricted nvcr.io image pulls. It authenticates those container pulls and hosted NVIDIA NIM inference inference endpoints — a models JSON entry with api_key_env: NGC_API_KEY sends it as the Authorization: Bearer token (refer to AI services — hosting models on NVIDIA NIM).

The model-servers-nim sample calls require_credentials("NGC_API_KEY"). This check is non-interactive and exits when the key is unavailable, so provide the key before starting the profile. Get a key at https://ngc.nvidia.com/setup/api-key, then export it:

export NGC_API_KEY=nvapi-xxx

To save it in the launcher credential store instead, run the interactive helper explicitly:

uv run --project utils/xr-ai-launcher python -c \
  "from xr_ai_launcher import ensure_credentials; ensure_credentials('NGC_API_KEY')"

How a token is resolved#

load_credentials(), require_credentials(), and ensure_credentials() resolve existing values in this priority order, highest first:

  1. Already set in os.environ

  2. Saved in ~/.config/xr-ai/credentials.json

  3. Stored in ~/.cache/huggingface/token (HF_TOKEN only)

ensure_credentials(...) adds an interactive fourth step: it prompts for any missing value and saves it for future runs. Samples and model_servers do not call this helper.

warn_if_missing(...) runs steps 1–3 and, if the token is still absent, prints an actionable notice and continues without prompting. require_credentials(...) runs the same steps but exits non-zero when the token is absent. model_servers --allow-anonymous relaxes only the HF_TOKEN check; credentials required by the selected NIM profile remain strict.

Managing saved tokens#

# View saved tokens
cat ~/.config/xr-ai/credentials.json

# Remove a token
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.config/xr-ai/credentials.json'
d = json.loads(p.read_text()); d.pop('HF_TOKEN', None); p.write_text(json.dumps(d, indent=2))
"