Setting up HuggingFace authentication
Some pipelines use gated models on HuggingFace that require authentication to download. A HuggingFace token is also used to obtain Cloudflare TURN credentials for WebRTC connections behind firewalls. You can create a token at huggingface.co/settings/tokens. Scope supports two ways to provide your token: through the Settings UI or via an environment variable.Using the API Keys Tab
To remove a stored token, click the delete button next to the entry.
If the
HF_TOKEN environment variable is already set, the input field is disabled.Using an Environment Variable
Setting theHF_TOKEN environment variable is the preferred method for headless, cloud, and CI deployments.
- Linux / macOS
- Windows (PowerShell)
The environment variable takes precedence over a token stored through the UI.
When Is a Token Needed?
| Scenario | Why |
|---|---|
| Gated model downloads | Pipelines that depend on gated HuggingFace models will fail with an authentication error without a valid token |
| Cloudflare TURN (WebRTC) | A token is used to obtain TURN server credentials for NAT traversal. Without it, Scope falls back to a public STUN server which may not work behind strict firewalls |
Troubleshooting
Authentication errors during model download
Authentication errors during model download
Verify that your token is set in Settings > API Keys or via the
HF_TOKEN environment variable.Token is set but downloads still fail
Token is set but downloads still fail
Ensure you have accepted the model’s license agreement on its HuggingFace page. Gated models might require explicit approval before access is granted.
WebRTC connection issues behind firewalls
WebRTC connection issues behind firewalls
Without a valid HuggingFace token, Scope cannot obtain Cloudflare TURN credentials and falls back to STUN-only mode. Set your token and restart Scope to enable TURN-based NAT traversal.