Credentials#

Overview#

Configure credentials for model downloads, inference services, and LiveKit connections. The required credentials depend on the models and deployment you use; the sections below describe their sources and precedence.

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 (the sample-local model-server commands). 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. Configure a token before starting a local model stack. 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. A token entered through ensure_credentials 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)#

Used for restricted nvcr.io image pulls and hosted NVIDIA inference. It authenticates those container pulls and hosted NVIDIA NIM 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).

Deploying self-hosted NIMs requires credentials in the operator’s deployment environment. Agents connecting to those endpoints need only their inference credentials. Configure each role’s endpoint.api_key_env with the environment variable accepted by its gateway; it need not be NGC_API_KEY. Refer to Deploying samples with NIM endpoints. 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 their model-server launchers 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. Local model-stack launchers require HF_TOKEN.

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))
"

Removing HF_TOKEN from the launcher store does not remove a token saved by Hugging Face login. Remove ~/.cache/huggingface/token as well if you want to disable that fallback, and unset HF_TOKEN in the launch environment.