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:

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

Equivalent Hugging Face CLI command to print the SSH command:

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

Enable Dev Mode:

```powershell
hf spaces dev-mode archivartaunik/NotebookLM
```

Disable Dev Mode:

```powershell
hf spaces dev-mode archivartaunik/NotebookLM --stop
```

Check Space status:

```powershell
hf spaces info archivartaunik/NotebookLM
```

Restart Space:

```powershell
hf spaces restart archivartaunik/NotebookLM
```

Factory rebuild if the normal restart keeps an old container:

```powershell
hf spaces restart archivartaunik/NotebookLM --factory-reboot
```

## Repo Workflow

Local repo remote:

```powershell
git remote -v
```

Expected remote:

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

Before pushing, sync with remote:

```powershell
git fetch origin
git rebase origin/main
```

Commit and push:

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

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

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

Check frontend from inside the Space:

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

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

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

Fetch build logs:

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

## Bextts / ZeroGPU Token

NotebookLM uses the public Bextts Space for Belarusian TTS:

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

```powershell
$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.