Let the agent manage Hugging Face repos when HF_TOKEN is set

Installs the official hf CLI (in a venv, since Debian's Python is
externally-managed) and, at boot, drops agents/hf-spaces.md in as opencode's
global AGENTS.md — the config-dir path applies to every session regardless of
which directory is open, so the guidance does not depend on a workspace file
that an ephemeral container would lose. With no HF_TOKEN present the file is
removed instead, so the instructions never advertise access the container
does not have.

The doc leads with "never print the token" because session transcripts are
shareable, and it draws the line at creating repos: deleting, renaming or
changing visibility needs the user's confirmation first. Image grows ~134MB
for python3 plus the CLI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Dockerfile

@@ -12,11 +12,24 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       jq \
       less \
       openssh-client \
+      python3 \
+      python3-venv \
       ripgrep \
       tar \
       unzip \
     && rm -rf /var/lib/apt/lists/*
 
+# Official Hugging Face CLI, so an agent holding HF_TOKEN can create and push
+# repos in one step instead of hand-rolling API calls. Debian marks its Python
+# externally-managed (PEP 668), hence the venv rather than a bare pip install.
+RUN python3 -m venv /opt/hf-cli \
+    && /opt/hf-cli/bin/pip install --no-cache-dir --upgrade pip \
+    && /opt/hf-cli/bin/pip install --no-cache-dir "huggingface_hub[cli]" \
+    && for bin in hf huggingface-cli; do \
+         [ -x "/opt/hf-cli/bin/$bin" ] && ln -sf "/opt/hf-cli/bin/$bin" "/usr/local/bin/$bin"; \
+       done \
+    && hf version
+
 # Install opencode at BUILD time so cold starts don't re-download the release.
 # The official installer hardcodes $HOME/.opencode/bin (it ignores
 # OPENCODE_INSTALL_DIR), so move the binary onto the shared PATH afterwards.
@@ -34,6 +47,7 @@ ENV HOME=/home/node
 ENV PATH=/usr/local/bin:${PATH}
 
 COPY --chown=node:node entrypoint.sh /home/node/entrypoint.sh
+COPY --chown=node:node agents/hf-spaces.md /home/node/agents/hf-spaces.md
 RUN chmod +x /home/node/entrypoint.sh \
     && mkdir -p /home/node/workspace \
     && chown -R node:node /home/node

README.md

@@ -104,6 +104,28 @@ your own domain needs `OPENCODE_CORS_ORIGINS=https://your.domain`.
 
 ---
 
+## Giving the agent Hugging Face access
+
+Set `HF_TOKEN` as a Space secret (or Railway variable) and the agent can create
+and manage Hugging Face repos: the official `hf` CLI is installed in the image,
+it picks the token up from the environment with no login step, and `entrypoint.sh`
+installs [`agents/hf-spaces.md`](agents/hf-spaces.md) as opencode's global
+`AGENTS.md` so the agent knows the recipes. With no `HF_TOKEN` set, that file is
+removed and nothing advertises the capability.
+
+> **This hands your HF account to whoever can reach the server.** A standard HF
+> write token covers every repo the account can write to — including org repos —
+> so the blast radius is much larger than "a shell in a container". Two things
+> make it meaningfully safer:
+>
+> - Use a **fine-grained token** scoped to just the permissions you need (write
+>   access to Spaces, say) rather than an account-wide write token.
+> - Remember the agent reads untrusted content — repos, web pages, issue text.
+>   Anything it reads can try to talk it into using the token. The instructions
+>   tell it never to print the token, but that is a speed bump, not a boundary.
+
+---
+
 ## Read this before you deploy
 
 - **This is a remote shell.** Every route allows command execution and file
@@ -131,6 +153,7 @@ your own domain needs `OPENCODE_CORS_ORIGINS=https://your.domain`.
 | `OPENCODE_STATE_ROOT` | `/data` | Where to look for a writable volume. |
 | `OPENCODE_WORKSPACE` | `$STATE_ROOT/workspace` or `$HOME/workspace` | Directory to serve. |
 | `OPENCODE_CORS_ORIGINS` | — | Comma-separated extra CORS origins. |
+| `HF_TOKEN` | — | Optional. A Hugging Face token, which lets the agent create and manage HF repos with the bundled `hf` CLI. See the warning below. |
 
 Build arg `OPENCODE_VERSION` pins a release (default: latest).
 

agents/hf-spaces.md

@@ -0,0 +1,83 @@
+# Hugging Face access
+
+`HF_TOKEN` is present in this container's environment and the official `hf` CLI
+is installed, so you can create and manage Hugging Face repos directly.
+
+**Never print, echo, cat or otherwise reveal the value of `HF_TOKEN`.** Pass it
+by variable reference only. Session transcripts can be shared, and this token
+carries write access to the whole account.
+
+## Who am I
+
+```bash
+hf auth whoami
+```
+
+The CLI reads `HF_TOKEN` from the environment; there is no login step.
+
+## Create a Space
+
+```bash
+hf repo create my-space --repo-type space --space_sdk docker
+```
+
+Then populate it. A Docker Space needs, at minimum, a `README.md` whose YAML
+front matter declares the SDK and the port your app listens on, plus a
+`Dockerfile`:
+
+```markdown
+---
+title: My Space
+emoji: 🚀
+colorFrom: gray
+colorTo: indigo
+sdk: docker
+app_port: 7860
+---
+```
+
+`app_port` must match what the container actually listens on. Hugging Face
+exposes exactly one port and routes it through HTTPS on 443 — a Space cannot
+serve a second port, and clients must not append a port to the `*.hf.space`
+URL.
+
+Upload files with the CLI:
+
+```bash
+hf upload <user>/<space> ./local-dir . --repo-type space
+```
+
+…or use git, keeping the token out of the stored remote:
+
+```bash
+git clone "https://huggingface.co/spaces/<user>/<space>" && cd <space>
+# commit files, then:
+git push "https://$(hf auth whoami | head -1):${HF_TOKEN}@huggingface.co/spaces/<user>/<space>" HEAD:main
+```
+
+## Set Space secrets
+
+Secrets are the only correct place for credentials — never commit them.
+
+```bash
+curl -sf -X POST "https://huggingface.co/api/spaces/<user>/<space>/secrets" \
+  -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
+  -d '{"key":"SOME_KEY","value":"...","description":"what it is for"}'
+```
+
+## Check whether a Space is up
+
+```bash
+curl -s "https://huggingface.co/api/spaces/<user>/<space>" | jq '.runtime.stage'
+```
+
+`RUNNING` is healthy. `BUILD_ERROR` / `RUNTIME_ERROR` / `CONFIG_ERROR` mean it
+failed — read the build logs on the Space page. Free `cpu-basic` Spaces are
+ephemeral and are stopped after roughly 48h idle, so anything that must survive
+belongs in git or on a persistent-storage mount at `/data`.
+
+## Ask before destroying things
+
+Creating repos is fine. Deleting or renaming an existing repo, changing its
+visibility, or overwriting someone else's files is not reversible — confirm with
+the user first.

entrypoint.sh

@@ -61,6 +61,26 @@ cd "$WORKSPACE"
 # which makes git refuse to touch the repo. Trust what we already control.
 git config --global --add safe.directory '*' 2>/dev/null || true
 
+# --- agent instructions ----------------------------------------------------
+# opencode reads a global AGENTS.md from its config dir (global.config/AGENTS.md),
+# which applies to every session regardless of which directory is open. Install
+# the Hugging Face guidance there when a token is actually present, so the
+# instructions never advertise a capability the container does not have.
+CONFIG_DIR="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}"
+if [ -n "${HF_TOKEN:-}" ] && [ -f "$HOME/agents/hf-spaces.md" ]; then
+  mkdir -p "$CONFIG_DIR"
+  {
+    echo "<!-- Generated by entrypoint.sh on boot. Edit agents/hf-spaces.md in the"
+    echo "     opencode-cloud repo instead; changes here are overwritten. -->"
+    echo
+    cat "$HOME/agents/hf-spaces.md"
+  } > "$CONFIG_DIR/AGENTS.md"
+  echo "hugging face: HF_TOKEN present, \`hf\` CLI available, agent instructions installed"
+else
+  rm -f "$CONFIG_DIR/AGENTS.md" 2>/dev/null || true
+  echo "hugging face: no HF_TOKEN set — agent has no Hugging Face access"
+fi
+
 # --- extra CORS origins ----------------------------------------------------
 # localhost, *.opencode.ai and the desktop app's oc://renderer are allowed out
 # of the box (packages/server/src/cors.ts). Only a frontend you host yourself