Skip to content

Deploying Potato on a Hugging Face Space

Run a Potato annotation task in a Hugging Face Docker Space with potato deploy, with annotations backed up to a private dataset every five minutes.

potato deploy up --provider huggingface runs an annotation task in a Hugging Face Docker Space, with HTTPS on an hf.space address and nothing to configure on a server. It suits a public demo of a task, and a lab whose data and models are already on the Hugging Face Hub. A Space's disk is wiped on every restart, so Potato keeps the annotations in a private Hugging Face dataset that it creates alongside the Space. It backs the annotations up to the dataset every five minutes and restores them when the Space starts. This page needs Potato 2.10 or later and a config you have already run with potato start.

Requirements and limits of a Space

Potato Spaces are Docker Spaces, and creating a Docker Space needs a paid Hugging Face plan, PRO for a personal account or Team or Enterprise for an organization. An account or organization on Hugging Face's free tier also runs at most three Spaces at once. A fourth stays PAUSED, and unlike a sleeping Space, a paused one never wakes when a visitor opens it.

For a study that runs for weeks with named annotators, a virtual machine such as AWS Lightsail, Jetstream2 or Hetzner keeps its disk across restarts, so the data does not depend on a backup. A Space fits best when the people you want to reach already have Hugging Face accounts, or when the task is a demonstration whose annotations you can afford to lose.

Setting up a Hugging Face token

Potato creates the Space and the dataset with your Hugging Face token. Create a token with write access in your Hugging Face settings, then install the Hugging Face extra and put the token in your environment:

bash
pip install 'potato-annotation[huggingface]'
export HF_TOKEN=hf_...
potato deploy providers --verify

providers --verify prints the account the token belongs to. Potato passes the token to the Space as a Space secret so the backup can write to the dataset, and never commits it to the Space's repository.

Deciding who can sign in

potato deploy does not change your sign-in settings, and a public Space can be opened by anyone with its address. If the config lets anyone register, the dry run below reports warning D003, "Anyone who finds the URL can register and annotate." Open registration usually suits a demo. For named annotators, list them under user_config.users with allow_all_users: false (Password Management), or have them sign in with their Hugging Face accounts, which Potato supports as a built-in provider under authentication.providers (SSO and OAuth).

Checking the plan and deploying

A dry run creates nothing and prints what the deploy would create:

bash
potato deploy up myproject/config.yaml --provider huggingface --dry-run

The plan creates the private dataset <account>/<name>-annotations, then a Docker Space <account>/<name>, sets the session key, the admin key and the token as Space secrets, and uploads your project with a Dockerfile and a README. The Dockerfile builds on the published Potato image for the version you have installed, so the Space holds only your project files. --owner deploys under an organization, --private makes the Space itself private, and --name overrides the name taken from the task.

Run the command without --dry-run and confirm the plan:

bash
potato deploy up myproject/config.yaml --provider huggingface

The deploy waits until the Space is running and prints its address, https://<account>-<name>.hf.space, and the path of the admin key file, .potato/secrets.json beside your config. The admin key opens the admin dashboard at /admin. A Space on free hardware sleeps after 48 hours without visitors and wakes when someone opens it, and the annotations come back from the dataset each time.

Ending the study

potato deploy pull downloads the backup dataset, which holds everything the Space has saved, rather than reading the Space itself:

bash
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroy deletes the Space and leaves the dataset in place, because deleting a Space can be undone by deploying again and deleting the annotations cannot. When you no longer need the dataset, delete it from its settings page on the Hub.

Deploying without a backup

--demo deploys the Space with no dataset, for a demonstration whose annotations do not matter. The dry run then warns that anything collected is lost on the next restart. Without a dataset, pull reads the running Space through the admin export, which works only while the Space is up.

Troubleshooting

A payment error on create means the account or organization has no paid plan. Docker Spaces need PRO for a personal account, or Team or Enterprise for an organization.

The Space is PAUSED when a free-tier account already runs three Spaces. Pause another one, then restart this one from its settings page. Restarting an existing Space does not need a paid plan.

Annotations are missing after a rebuild when the Space could not restore from the dataset. The Space log shows a RESTORED line on a successful restore, and its absence usually means the HF_TOKEN Space secret is missing or lacks write access.

BUILD_ERROR is explained in the build log at https://huggingface.co/spaces/<account>/<name>?logs=build.

Further reading