README.md

---
title: JupyterLab with Beszel Agent
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# JupyterLab with Beszel Agent

This Hugging Face Docker Space runs JupyterLab on port `7860` and starts a
`beszel-agent` process in the same container.

## Required Space secrets

Add these values in `Settings -> Variables and secrets -> Secrets`:

- `JUPYTER_TOKEN`
- `BESZEL_KEY`
- `BESZEL_TOKEN`
- `BESZEL_HUB_URL`

Optional:

- `BESZEL_SYSTEM_NAME`
- `BESZEL_LISTEN`
- `JUPYTER_ROOT_DIR`
- `BESZEL_DATA_DIR`
- `SKIP_GPU`

## Important notes

- Hugging Face Docker Spaces expose a single public port. JupyterLab is served
  on `7860`.
- `beszel-agent` uses an outgoing WebSocket connection to the hub, so there is
  no need for `--network host`.
- Docker monitoring is intentionally disabled because Docker Spaces do not
  expose `/var/run/docker.sock`.
- Notebook files are stored in `/data/workspace`.
- Beszel agent state is stored in `/data/beszel-agent`.
- If `BESZEL_SYSTEM_NAME` is not set, the startup script falls back to the
  built-in `SPACE_ID` runtime variable when available.
- Without persistent storage, both directories are ephemeral and may be lost on
  restart.
- For long-running monitoring, use paid hardware or a custom sleep policy. Free
  CPU Spaces can go to sleep after inactivity.

## What this Space can monitor

- JupyterLab availability
- CPU, memory, disk, and network usage of the Space container
- Beszel agent online/offline status

## What this Space cannot monitor

- Per-container Docker metrics inside the Space
- Host-level metrics outside the Hugging Face Space runtime