Inject a Hugging Face token into an sbx sandbox
This guide explains how to make a Hugging Face token usable in a Docker sandbox (sbx) without storing the real token in the container.
Status:
sbx secret set-customis experimental. Its behavior, options and placeholder format may change.
How it works
Hugging Face is not one of the services built into sbx (like github). You therefore use a custom secret:
- Inside the sandbox, the
HF_TOKENvariable holds a placeholder (sbx-cs-…). - The real token stays on the host machine, in the operating system's keychain.
- When a process in the sandbox sends an HTTP request to one of the declared domains, the proxy replaces the placeholder with the real token, in HTTP headers only, not in the request body.
For Hugging Face, that is enough: the token is sent in the Authorization: Bearer … header.
Set up the secret
All sbx commands run on the host machine, not in the sandbox.
The secret is global: without --sandbox, it applies to every sandbox, so both the dev sandbox (houla-houla, sbxenv.dev.yaml) and the Olala sandbox (houla-olala, sbxenv.yaml). There is only one command to run, once.
printf '%s' "hf_xxx" | sbx secret set-custom \
--host huggingface.co \
--host '*.huggingface.co' \
--env HF_TOKEN \
--value-stdin
| Option | Purpose |
|---|---|
--host |
Domain the token is sent to. Repeatable. * matches a single subdomain level (e.g. router.huggingface.co, cdn-lfs.huggingface.co), ** matches several. |
--env |
Name of the environment variable set in the sandbox. |
--value-stdin |
Reads the token from standard input (recommended). Without this option, the command prompts for the value. |
--sandbox <name> |
Restricts the secret to a single sandbox. Not used here: we want the secret everywhere. |
--ref |
Reads the token from an external source when needed, e.g. op://Vault/Item/credential (1Password). |
--command |
Reads the token when needed by running a command on the host that prints it. |
--refresh |
How long a token read by --ref or --command is cached (<duration> or on-demand). |
Warning: avoid
--value hf_xxx: the token would end up in your shell history and in the process list.
To check that the secret is registered:
sbx secret ls --host huggingface.co
Check inside the sandbox
echo "$HF_TOKEN" # prints the placeholder, not the real token
hf auth whoami # should print your Hugging Face account
Possible problems
-
HF_TOKENis empty in an existing sandbox: for built-in secrets (likegithub), a global secret only applies to sandboxes created afterwards. It is probably the same here (not verified): recreate the sandbox, e.g.sbx env rm sbxenv.dev.yamlthensbx env create sbxenv.dev.yaml. For a single existing sandbox, you can also re-run the command with--sandbox <name>(forgithub, a sandbox-scoped secret applies immediately). -
A tool rejects the placeholder because it does not start with
hf_: a--placeholderoption would let you choose its format (e.g.--placeholder 'hf_{rand}'). It does not appear on the detailed docs page: check it withsbx secret set-custom --help. -
HTTP 403 error "no matching allow rule": the domain is blocked by the sandbox firewall. On the host:
sbx policy allow network huggingface.co,cdn-lfs.huggingface.co
Don't
Don't put the token in the env: section of sbxenv.yaml or sbxenv.dev.yaml: these files are meant to be committed, and the token would end up in the repository.
References
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 |
|