bots-garden/houlapublic Fork
⑂ main
Commits
⬇ Clone ▾
git clone https://git.rickub.com/bots-garden/houla.git
git clone ssh://git@rickub.com/bots-garden/houla.git

Host key fingerprint (ed25519): SHA256:iycHnxEyq0Q7uyVpB7JlznP0G7JrTPXLYRcAU5CSLhc — verify it before your first connect.

Download ZIP
🛟 Updated. 1dfc968Unverified · on main · k33g · 3h ago
huggingface-token-sbx.en.md · 74 lines · 3.9 KBmarkdown
Blame HistoryOpen raw

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-custom is 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_TOKEN variable 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_TOKEN is empty in an existing sandbox: for built-in secrets (like github), 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.yaml then sbx env create sbxenv.dev.yaml. For a single existing sandbox, you can also re-run the command with --sandbox <name> (for github, a sandbox-scoped secret applies immediately).

  • A tool rejects the placeholder because it does not start with hf_: a --placeholder option would let you choose its format (e.g. --placeholder 'hf_{rand}'). It does not appear on the detailed docs page: check it with sbx 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
# 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-custom` is **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_TOKEN` variable 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.

```bash
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:

```bash
sbx secret ls --host huggingface.co
```

## Check inside the sandbox

```bash
echo "$HF_TOKEN"     # prints the placeholder, not the real token
hf auth whoami       # should print your Hugging Face account
```

## Possible problems

- **`HF_TOKEN` is empty in an existing sandbox**: for built-in secrets (like `github`), 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.yaml` then `sbx env create sbxenv.dev.yaml`. For a single existing sandbox, you can also re-run the command with `--sandbox <name>` (for `github`, a sandbox-scoped secret applies immediately).
- **A tool rejects the placeholder because it does not start with `hf_`**: a `--placeholder` option would let you choose its format (e.g. `--placeholder 'hf_{rand}'`). It does not appear on the detailed docs page: check it with `sbx secret set-custom --help`.
- **HTTP 403 error "no matching allow rule"**: the domain is blocked by the sandbox firewall. On the host:

  ```bash
  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

- [Manage credentials – Docker Sandboxes](https://docs.docker.com/ai/sandboxes/configuration/credentials/)
- [`sbx secret set-custom`](https://docs.docker.com/reference/cli/sbx/secret/set-custom/)
- [`sbx secret`](https://docs.docker.com/reference/cli/sbx/secret/)