Put Your Potato Study Online

Get a Potato task from your computer to your annotators by asking IT, clicking a prepared deploy button, sharing from a laptop, or renting a server.

To put a Potato study online, you run your task on a computer that your annotators can reach through a web address, keep the annotations safe while the study runs, and download the annotations at the end. Asking your institution's IT team and clicking a deploy button that a colleague prepared are the two routes that need no terminal on your side.

Deploying a study means moving the Potato task you built from your own computer to a server, a computer that stays switched on and connected to the internet. Annotators then open the task in a web browser from anywhere, and Potato saves each answer on the server as annotators work. The Study Designer preview runs Potato inside your own browser, and nobody else can reach that copy. A study built in the Designer still needs one of the routes below.

Every route starts from the same project folder. In the Study Designer, the Download project (.zip) button saves config.yaml (the file that describes your task), a sample data file, and a README. The sample file holds three placeholder items. Replace the sample file with your own items before you deploy, in the format Data Formats describes.

Choosing a route

The routes differ in who does the technical work, what the server costs, and how long the study can stay up. The costs below come from the hosts' price lists and Potato's own estimates on 2026-11-04, and the waits are rough guides rather than measurements:

Route	Suits	Cost	Terminal needed	Typical wait
Ask your IT or research computing team	sensitive data, institutional sign-in, studies that run for months	set by your institution	not by you	days to weeks
Click a deploy button a colleague prepared	a lab with one person who uses git	free on Render, $7 a month on Heroku	not by you	the same day
Share from your own computer	a pilot or a lab meeting, for an afternoon	free	yes, a few commands	an hour or two
Rent a server with one command	a study that runs for weeks, run by you	about €6 to $12 a month, or free on Jetstream2	yes, plus a cloud account	an afternoon

If you are unsure, start with your IT team. A server inside your institution keeps the data on equipment your institution already manages, and the IT team can take on security updates and backups.

Ask your IT or research computing team

Many universities and hospitals run a research computing service that hosts web applications for studies. To such a team, Potato is an ordinary web application, and the team can start from a one-page summary of what Potato needs.

Download the project from the Study Designer, and replace the sample data file with your items.
Send your IT team the project folder and a link to Potato Server Requirements for Your IT Team.
Tell the team who your annotators are, how many will take part, and how long the study runs.
Say how annotators should sign in. Colleagues with institutional accounts can use single sign-on, the login your institution already runs, and outside annotators can use usernames you list.
Say whether the items or the answers contain personal or sensitive information, and name the ethics approval the study runs under.
Ask the team for the study's web address, the admin key that opens Potato's admin dashboard, and a plan for backups and for handing you the data when the study ends.

When the address arrives, work through Before you invite annotators before you send the address to anyone.

Click a deploy button a colleague prepared

A deploy button is a link on a code repository's page that sets up a copy of a Potato task on a hosting company's servers, entirely through forms in your browser. A colleague who uses git and a terminal makes the button once, from a repository that holds your project folder, with the potato deploy button command. Running Potato Locally or in the Cloud is the page to send that colleague.

The button works with three hosts, which charge differently:

Render runs the study on a free plan with no payment method. A free Render service goes to sleep after 15 minutes without visitors and takes about a minute to wake when the next annotator arrives.
Heroku charges $7 a month for the server the button creates. Heroku requires a verified account, usually through a credit card, before you can create an app.
AWS runs a Lightsail server for $12 a month. The AWS button reads the task from a public repository, so the AWS button suits only items that can be public.

Render and Heroku wipe the server's disk whenever the server restarts. The button therefore copies the annotations every five minutes to a private dataset on Hugging Face, a site for sharing data and models, and copies the annotations back whenever the server starts. You name that dataset when you click, and the dataset belongs to your account.

Before you click, gather three things:

an account on the host, Render or Heroku;
a free Hugging Face account, with an access token that has write permission, made at huggingface.co/settings/tokens; and
access to the repository, if the repository is private. Heroku asks you to link your GitHub account for a private repository.

Then deploy:

Click the button in the repository's README, and sign in to the host.
Give the app a name. The name becomes part of the study's web address.
In POTATO_BACKUP_HF_REPO, type a dataset name made of your Hugging Face username and a name for the study, such as your-username/my-study-annotations. When the name is new, Potato creates the dataset and makes the dataset private.
Paste your Hugging Face token into HF_TOKEN. Leave every other field at the value the button filled in.
Start the deploy and wait for the host to report that the app is running. Open the web address the host shows.
Find the admin key, a password the host generated during the deploy. On Heroku the key is the POTATO_ADMIN_API_KEY entry on the app's Settings tab, and on Render the same entry is on the service's Environment page.
Open the study address with /admin added to the end, and paste the admin key to open the admin dashboard.

The repository fixes the task, the items, and the list of annotators. Finish the task before you click, because any later change goes through the colleague who made the button. Keep the repository private unless the items can be public.

Your own computer can serve a pilot for an afternoon. Annotators open a temporary web link, the annotations land in your project folder, and the link stops working when you close the command. The route needs a terminal, a program for typing commands, which is Terminal on a Mac (in Applications, then Utilities) and PowerShell on Windows (search for "PowerShell" in the Start menu).

Install Python 3.9 or newer from python.org/downloads. On Windows, the download is the Python install manager. On a Mac, the download is the macOS installer.
Open the terminal and install Potato. On a Mac, type:
bash
```
python3 -m pip install potato-annotation
```
On Windows, type:
powershell
```
py -m pip install potato-annotation
```
Unzip the project you downloaded from the Study Designer. On a Mac, double-click the .zip file. On Windows, right-click the file and choose Extract All. Replace the sample data file with your items.
Move the terminal into the project folder and start Potato. The folder name below is an example, so use the name of your own folder. On a Mac:
bash
```
cd ~/Downloads/my-task
python3 -m potato start config.yaml
```
On Windows:
powershell
```
cd $HOME\Downloads\my-task
py -m potato start config.yaml
```
Open http://localhost:8000 in your browser. Only your computer can reach that address. Press Ctrl-C in the terminal to stop Potato.
To let other people in, install cloudflared, a free program from Cloudflare that needs no account. On a Mac with Homebrew, run brew install cloudflared. On Windows, download the Windows installer from Cloudflare's downloads page.
Run potato share in place of potato start:
bash
```
python3 -m potato share config.yaml
```
On Windows, type py -m potato share config.yaml. Potato prints who will be able to sign in and asks before publishing anything. Type y, and Potato prints an https:// link to send to your annotators.

The link works only while the command runs. Closing the terminal, putting the computer to sleep, or changing networks ends the link, and a new run prints a new link. Some university networks block the trycloudflare.com links that cloudflared makes. If an annotator reports a blocked link, potato share config.yaml --backend tailscale uses Tailscale instead. Tailscale needs a free account. If potato share reports No tunnel backend found, Potato could not find cloudflared on your computer, and the message lists the install commands.

Installation covers virtual environments and optional features, and Running Potato Locally or in the Cloud covers potato share in more detail.

Rent a server with one command

potato deploy up rents a server from a cloud company, gets an HTTPS certificate (the padlock in the browser's address bar), uploads your project folder, starts the study, and prints the web address. The command needs the terminal setup from steps 1 to 3 above, an account with the cloud company, and an API token, a password-like key that lets a program act on your account. Each host's guide covers the account and the token from the start:

Host	Monthly cost	Guide
AWS Lightsail	$12	AWS Lightsail
Hetzner, Vultr or Linode	about €6 to $12	Hetzner, Vultr and Linode
Jetstream2, for US researchers	free with an ACCESS allocation	Jetstream2
A Hugging Face Space	a Hugging Face PRO plan, $9	Hugging Face Spaces

Every host takes the same two commands, and the guide for each host gives the provider name and the install command for the host. The first command shows the plan and the monthly cost and creates nothing, and the second creates the server after you confirm:

bash

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Hugging Face's own Duplicate this Space button copies a Space in the browser, but a copy of a Potato Space keeps the original owner's backup settings and loses the original's secrets. Deploy a Potato Space with potato deploy up --provider huggingface instead.

Before you invite annotators

Run through this list once the study has a web address, whichever route you took:

Decide who can sign in. The simplest closed setup is a list of usernames. In the Study Designer, turn off Allow All Users and add each annotator under Authorized Users. Each listed annotator chooses a password when registering on the first visit, and Potato refuses anyone not on the list. Send each annotator the username directly, because the first person to register a listed username owns that account. For institutional accounts, see SSO and OAuth, and for crowdworkers, see Crowdsourcing Integration. With Allow All Users turned on, anyone who finds the address can create an account. Keep that setting for public demos.
Know where the annotations live. Potato saves each annotator's answers as the annotator works, in a file named user_state.json inside one folder per annotator. The folders sit in the output folder the config names, which the Study Designer calls output. On your own computer, that folder is inside your project folder. On a button deploy, the Hugging Face dataset holds the copy that survives a restart. On a rented server, potato deploy pull downloads the folder. On an institutional server, ask IT how the server is backed up.
Test with a second browser. Open the study address in a private window, which is Incognito in Chrome, Private Window in Safari and Firefox, and InPrivate in Edge. Add a username such as pilot-test to the list, register with that name, and answer three items. Close the window, sign in again, and check that the answers are still there. Then open the admin dashboard and check that the test annotator appears. Try the address on a phone if annotators might work on phones.
Keep the admin key private. The admin key opens the admin dashboard at /admin. The dashboard shows every annotator's answers. On your own computer, Potato saves the key in admin_api_key.txt in the project folder the first time you open /admin.
Write the invitation. Send each annotator the address, the username, how long the task takes, and whom to contact when something goes wrong.

Getting your results

The admin dashboard downloads the results to your computer with no terminal. Open /admin, enter the admin key, and choose Publish Dataset. Under Target, choose Local archive, set Data format to CSV for a spreadsheet, and click Publish. When the archive is ready, click Download archive.

The archive holds each annotator's answers, the items, and labels combined by majority vote. A README in the archive reports label counts and agreement between annotators. Annotator names are replaced with A1, A2 and so on unless you untick Anonymize annotators. Survey answers stay out of the archive unless you tick Include survey / phase responses, because survey answers may contain personal information.

From a terminal, python -m potato.export writes the same annotations to a folder, in any of Potato's export formats:

bash

python -m potato.export --config config.yaml --format csv --output results

On a server made with potato deploy up, potato deploy pull config.yaml downloads everything the server collected, databases included.

Ending the study so the server stops costing money

Download the results before you remove anything, and open the download to check that the last annotator's answers are there. Then shut the server down the way the route requires:

Your own computer. Press Ctrl-C in the terminal. Nothing was charged.
Your IT team. Tell the team the study has ended, ask for a copy of the output folder, and ask how long the server copy will be kept.
A deploy button. Delete the app from the app's Settings tab on Heroku, or delete the service from its Settings page on Render. The Hugging Face dataset holds a full copy of the annotations. When you no longer need the backup, delete the dataset from the dataset's settings page.
A rented server. Run potato deploy pull config.yaml, check the pulled folder, and then run potato deploy destroy config.yaml. Potato refuses to destroy a server whose data has never been pulled.

Common questions

How do I create a Potato server for my study?

You create a Potato server by running your task on a computer that your annotators can reach through a web address. Your institution's IT team can run the task for you, a colleague can prepare a deploy button that you click, potato share can serve a pilot from your laptop, and potato deploy up can rent a server for you. The table under Choosing a route compares the routes by cost and by the terminal work each route needs.

How do I install Potato on my PC?

Install Python 3.9 or newer from python.org, then type py -m pip install potato-annotation in PowerShell on Windows, or python3 -m pip install potato-annotation in Terminal on a Mac. After the install, py -m potato start config.yaml on Windows or python3 -m potato start config.yaml on a Mac starts a task. Installation covers the optional features.

Words used on this page

Server. A server is a computer that stays on and connected to the internet so that other people can use a program on the computer through a web browser.
URL, or web address. A URL is the address annotators type or click, such as https://my-study.example.edu. A domain is the name part of the address, here my-study.example.edu.
HTTPS. HTTPS encrypts everything between the annotator's browser and the server, including passwords and answers. Browsers show a padlock for an HTTPS address.
Port. A port is a numbered entry point on a computer. Potato listens on port 8000 unless the config names another port, and the local address http://localhost:8000 ends in that number.
Terminal. A terminal is a program for typing commands, called Terminal on a Mac and PowerShell on Windows.
Admin key. The admin key is a long password that opens Potato's admin dashboard.
API token. An API token is a password-like key that lets a program, such as Potato's deploy command, act on your account at a hosting company.