---
title: MeshScale
emoji: 🔩
colorFrom: gray
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# MeshScale

Bare-metal search surface for the MeshScale CPU worker mesh.

Required Space variable:

```text
KEY_FARM_ROOT=/data/farm
```

Safe default:

```text
MESHSCALE_ENABLE_APPLY=0
MESHSCALE_AUTOSCALE=0
```

Set `MESHSCALE_ENABLE_APPLY=1` only on the controller Space that is allowed to
start or pause Hugging Face CPU worker Spaces.
Set `MESHSCALE_AUTOSCALE=1` on that same controller when expansion requests
should be honored continuously instead of only through `scale apply`.

Operator write guard:

```text
MESHSCALE_OPERATOR_TOKEN=<long random operator token>
MESHSCALE_REQUIRE_OPERATOR_TOKEN=true
```

When configured, mutating HTTP routes require `X-MeshScale-Token`. Read-only
status, dashboard, route, and plan endpoints stay open. The UI can store the
token locally with `auth <token>` and remove it with `auth clear`; the token is
not echoed into the output pane.

Common variables:

```text
MESHSCALE_TEMPLATE_SPACE=tostido/meshscale-worker-template
MESHSCALE_SCALE_MODE=auto
MESHSCALE_REPLICA_SPACE=tostido/meshscale-worker-template
MESHSCALE_WORKER_POOL=tostido/meshscale-worker-template
MESHSCALE_MIN_REPLICAS=1
MESHSCALE_NAMESPACE=tostido
MESHSCALE_WORKER_PREFIX=meshscale-worker
MESHSCALE_HARDWARE=cpu-upgrade
MESHSCALE_MAX_WORKERS=24
MESHSCALE_BUDGET_HOURLY_USD=1.44
MESHSCALE_AUTOSCALE_SECONDS=30
MESHSCALE_BUCKET_SOURCE=tostido/Ouroboros-storage
MESHSCALE_BUCKET_MOUNT_PATH=/data
MESHSCALE_KEY_SPACE_URL=https://huggingface.co/spaces/tostido/Ouroboros
MESHSCALE_BUCKET_URL=https://huggingface.co/buckets/tostido/Ouroboros-storage
MESHSCALE_WORKER_TEMPLATE_URL=https://huggingface.co/spaces/tostido/meshscale-worker-template
```

`auto` mode tries replica scaling first. It drives:

```text
POST https://huggingface.co/api/spaces/{namespace}/{repo}/replicas
```

against `MESHSCALE_REPLICA_SPACE`, avoiding the Hugging Face daily duplicate
repository cap. If Hugging Face rejects replica mutation for the current
account/token, MeshScale starts already-created workers listed in
`MESHSCALE_WORKER_POOL`. The old duplicate-repo path remains available with
`MESHSCALE_SCALE_MODE=spaces`.

The UI accepts search commands:

```text
guide
status
trace
plan 420
scale <n>
scale 0
scale dry
scale apply
run
drain 4
shutdown
```

The OS route layer returns contextual next steps before acting. For example,
`scale apply` stops early when the controller pulse is quiet and routes the user
to KEY instead of blindly scaling workers.