HF_SPACE_CONNECTION.md

Hugging Face Space Connection Notes

Space: https://huggingface.co/spaces/archivartaunik/NotebookLM

Runtime URL: https://archivartaunik-notebooklm.hf.space

Repo: https://huggingface.co/spaces/archivartaunik/NotebookLM

Local workspace: D:\CodexPRJ\OpenNotebook

Hugging Face account currently used by hf CLI: archivartaunik

SSH / Dev Mode

Dev Mode SSH command:

ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space

Equivalent Hugging Face CLI command to print the SSH command:

hf spaces ssh archivartaunik/NotebookLM --dry-run -i C:\Users\admin\.ssh\hagginfacekey

Enable Dev Mode:

hf spaces dev-mode archivartaunik/NotebookLM

Disable Dev Mode:

hf spaces dev-mode archivartaunik/NotebookLM --stop

Check Space status:

hf spaces info archivartaunik/NotebookLM

Restart Space:

hf spaces restart archivartaunik/NotebookLM

Factory rebuild if the normal restart keeps an old container:

hf spaces restart archivartaunik/NotebookLM --factory-reboot

Repo Workflow

Local repo remote:

git remote -v

Expected remote:

origin  https://huggingface.co/spaces/archivartaunik/NotebookLM (fetch)
origin  https://huggingface.co/spaces/archivartaunik/NotebookLM (push)

Before pushing, sync with remote:

git fetch origin
git rebase origin/main

Commit and push:

git add <files>
git commit -m "Your commit message"
git push origin main

Important: changes made directly inside Dev Mode SSH are not safely preserved unless committed and pushed from inside the Space or copied back to the local repo and pushed.

Useful Runtime Checks

Check that SSH reaches the Space:

ssh -o StrictHostKeyChecking=accept-new -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "pwd && echo SSH_OK"

Check API health from inside the Space:

ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "curl -fsS http://localhost:5055/health"

Check frontend from inside the Space:

ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "curl -fsS -o /dev/null -w 'frontend_http=%{http_code}\n' http://localhost:8502"

Check important processes:

ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "ps -eo pid,stat,comm,args | grep -E 'supervisord|uvicorn|next-server|surreal-command|surreal start' | grep -v grep"

Fetch run logs:

$env:PYTHONIOENCODING='utf-8'
hf spaces logs archivartaunik/NotebookLM --tail 120

Fetch build logs:

$env:PYTHONIOENCODING='utf-8'
hf spaces logs archivartaunik/NotebookLM --build

Bextts / ZeroGPU Token

NotebookLM uses the public Bextts Space for Belarusian TTS:

hf spaces info archivartaunik/Bextts --expand runtime

The Bextts Space runs on ZeroGPU, so NotebookLM must call it with an authenticated Hugging Face token. Store the token as a NotebookLM Space secret:

$token = hf auth token
hf spaces secrets add archivartaunik/NotebookLM -s "HF_TOKEN=$token"

At startup, start-hf.sh copies HF_TOKEN into the Bextts model credential config as the provider API key. Without this, Bextts calls are anonymous and can fail with Bextts generation failed while Bextts logs show ZeroGPU quota exceeded.

Current Notes

• Dev Mode requires the Docker image to include git. The Dockerfile currently installs bash, curl, git, git-lfs, procps, and wget.
• The previous startup crash was caused by a directory named /app/frontend/node_modules/next/dist/compiled/ipaddr.js. start-hf.sh now skips non-files before calling read_text().
• Current known good commit after that fix: fb2282d.
• Do not store Hugging Face access tokens or service account secrets in this document.