Credentials#

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

DeviceIOHub also requires a LiveKit API key and secret. Set api_key and api_secret in device_io_hub.yaml, or supply LIVEKIT_API_KEY and LIVEKIT_API_SECRET in the environment. Environment values override the YAML fields, which lets deployed stacks inject credentials without rewriting the configuration file. Both values are required; the hub fails at startup when either is missing or blank instead of silently using development 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 vlm_llm_nim model-server profile 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))
"