Guides and reference for deploying oTree experiments.
TreeHost is a hosting platform for behavioural researchers using oTree. It gives each researcher an isolated environment with oTree, Postgres, and Redis — accessible over HTTPS at a dedicated subdomain — without any server setup.
jsmith-spring26) and an oTree version.your-id.treehost.io.TreeHost supports three sign-in methods. All three use your email address to identify your account — signing in via different methods with the same email will access the same account.
Click Continue with GitHub. You'll be redirected to GitHub to authorise the app. TreeHost receives your public profile and primary email address. No GitHub data is stored beyond your name, email, and avatar URL.
Click Continue with Google. You'll be redirected to Google to authorise the app. TreeHost receives your name, email, and profile photo.
Enter your email address and click Send magic link. You'll receive an email with a sign-in link that is valid for 15 minutes and can only be used once. No password required.
Same email = same account. If you sign in via GitHub today and Google tomorrow using the same email address, you'll see the same dashboard and workspaces both times.
Each workspace is a fully isolated environment running oTree, Postgres, and Redis. It gets a dedicated subdomain on treehost.io.
The Workspace ID becomes part of your URL: your-id.treehost.io. Rules:
Good examples: jsmith-pilot, lab2-trust-game, econ101-spring26
Choose the oTree version your project requires. If you're not sure, use the latest (shown as "latest" in the dropdown). The version can't be changed after a workspace is created — create a new workspace if you need a different version.
You can upload your project zip at creation time, or upload it later from the dashboard. The workspace will be provisioned either way; you just won't be able to run experiments until a project is uploaded.
TreeHost validates every upload to ensure it's a valid oTree project. Understanding these requirements will save you time.
.otreezip file (recommended)oTree can export your project as a .otreezip file directly from its admin panel: go to oTree admin → Data → Download code. TreeHost accepts .otreezip files natively — just upload the file as-is, no rezipping required.
.otreezip is the easiest option. It's produced by oTree itself and always contains the right structure. Use it whenever you can — especially if you're migrating a project from another oTree server.
.zip manuallyIf you don't have an .otreezip, you can zip your project manually. Zip the contents of your oTree project directory — not the directory itself. Your settings.py should be at the root of the zip (or at most one level deep).
# Correct — settings.py at root
zip -r project.zip settings.py requirements.txt public_goods/ trust_game/
# Also correct — contents of the directory
cd my-otree-project/
zip -r ../project.zip .Don't include the outer directory. If your zip contains a single folder like my-project/settings.py, the upload may fail validation. Zip the files directly, not the folder.
TreeHost validates the following when you upload:
.zip or .otreezip filesettings.py with SESSION_CONFIGSTo keep your zip small and clean:
__pycache__/, .git/, and venv/ directories.env files (environment variables are configured by TreeHost)# Using .zipignore equivalent with zip -x
zip -r project.zip . \
-x "*.pyc" -x "__pycache__/*" -x ".git/*" \
-x "venv/*" -x ".env"You can upload a project when creating a workspace, or at any time afterward from the dashboard.
On your workspace card, click the upload area or the file icon to select a .zip or .otreezip file. If the workspace already has a project, you'll be asked to confirm before replacing it.
/uploads/project.zipUploading a new project restarts oTree. Any active participant sessions will be interrupted. Upload a new project before your session starts, not during it.
A workspace moves through several states from creation to ready. The dashboard updates automatically.
Helm is creating the Kubernetes namespace, Postgres, Redis, and oTree containers. Takes 30–60 seconds.
Infrastructure is ready but oTree is still initialising. The Open button is disabled during this phase.
Workspace is live and accessible. Click Open to visit your oTree instance.
Deployment encountered an error. Click Retry to try again. If it fails repeatedly, contact support.
The dashboard polls for status updates every 5 seconds while a workspace is deploying or starting. The page reloads automatically when the status changes.
Your workspace is protected by authentication — only you can open it directly. Participants access it via an oTree session link.
Click the Open button on your workspace card, or navigate directly to your-id.treehost.io. You'll be redirected to sign in if you don't have an active session.
Participants should be given a direct session link from oTree — not the bare workspace URL. From the oTree admin panel:
Participant links bypass authentication — participants do not need a TreeHost account.
Tearing down permanently deletes the workspace, its database, and all associated data. This action cannot be undone.
The workspace and its Kubernetes namespace are removed immediately. The workspace ID becomes available for reuse.
oTree has gone through two major architectural generations, and several breaking releases within the current one. This guide helps you pick the right version for your project — whether you're starting fresh or migrating an existing experiment.
oTree 3.x and oTree 5.x are fundamentally different frameworks that happen to share a name.
| oTree 3.x (legacy) | oTree 5.x / 6.x (current) | |
|---|---|---|
| Web framework | Django | Starlette (async) |
| Database layer | Django ORM | SQLAlchemy |
| Models | Class-based with models.py |
Inline in __init__.py per app |
| TreeHost support | Not supported | Supported |
oTree 3.x projects will not run on TreeHost. If you have an oTree 3 project, you'll need to migrate it to oTree 5 before uploading. The oTree migration guide covers the key changes.
Within the 5.x series, several releases introduced breaking changes that can silently affect experiment results. The most important ones are:
| Version | What changed | Risk |
|---|---|---|
| 5.2 | Built-in fields renamed — id becomes id_in_group, round_number stays but internal field names gained an id_ prefix. Timestamps are now UTC. |
Medium — data export column names change |
| 5.9 | Template tag {% formInputs %} renamed to {% forminputs %} (lowercase). |
Low — causes a template error, easy to fix |
| 5.10 | Numeric fields now default to min=0 unless you explicitly set min=None. Participants can no longer enter negative numbers without a code change. |
High — silently blocks valid responses in many economics experiments |
The oTree 5.10 min=0 change is the most common source of silent data loss. If your experiment has a field like IntegerField() where participants might enter a negative number, you must add min=None explicitly when running on 5.10 or later:contribution = models.IntegerField(min=None, max=100)
oTree 6 is largely backwards-compatible with oTree 5.11+. Most 5.x projects will run on 6.x without changes. The notable exceptions are:
live_method instead of a direct reference, this breaks in oTree 6. Change live_method = "my_method" to live_method = my_method.If your project doesn't use live pages or custom chat widget styling, upgrading from 5.11 to 6.x is typically straightforward.
Use this decision guide:
min=None on any numeric field where negative values are valid.min=0 default is worth checking regardless.When creating a workspace, the version dropdown shows all versions currently available. TreeHost offers:
min=0 default change; a safe target for projects written before 5.10min=0 default in placeThe version cannot be changed after a workspace is created. If you need a different version, create a new workspace and upload your project there.
Not sure which version your project was written for? Check the otree line in your requirements.txt. If there is no requirements.txt, check the oTree admin panel's About page once the workspace is running — it shows the running version.
TreeHost workspaces include a curated set of research packages out of the box. If your project needs a package that isn't pre-installed, you can request it through the dashboard.
The following packages are available in every workspace without any extra steps:
| Package | Common use |
|---|---|
openai | LLM-augmented experiments (OpenAI API) |
anthropic | LLM-augmented experiments (Claude API) |
httpx | HTTP requests to external APIs |
pandas | Data manipulation and analysis |
numpy | Numerical computing (also a pandas dependency) |
scipy | Statistical computing |
statsmodels | Econometrics and regression |
openpyxl | Read and write .xlsx files |
xlrd | Read legacy .xls files |
Just import these in your oTree code — no requirements.txt needed for pre-installed packages.
If your project needs a package that isn't pre-installed, add a requirements.txt to your project listing the packages it needs. When you upload the project, the workspace will fail to start — this is expected. From there:
requirements.txt is sent to the TreeHost team for review.Each startup, your packages are installed fresh from requirements.txt and scanned for known security vulnerabilities before oTree launches. If a package fails the scan, the workspace will not start and you'll see an error in the Why? panel.
If the admin dismisses your request, you'll receive an email with the reason. Your workspace card will also show the dismissal reason when you click Why?. To re-request:
requirements.txt to address the issue raised.You must upload a revised project before re-requesting — the button will remain disabled until you do.
Some packages are not supported due to resource or compatibility constraints:
torch, tensorflow, transformers, spacy with model downloads. These exceed available memory (512 MB) and will cause the workspace to crash on startup.If your experiment requires a heavy framework or has other unusual package needs, contact us at [email protected] to discuss options.
TreeHost supports oTree 5.x and 6.x. The available versions are shown in the version dropdown when creating a workspace. oTree 3.x is not supported. For guidance on choosing a version, see Choosing the right oTree version.
Your settings.py must define SESSION_CONFIGS (required by all oTree 5 projects). Do not set DATABASE_URL, REDIS_URL, or OTREE_PORT — these are configured automatically by TreeHost.
Do not hardcode SECRET_KEY in your project. If you set it, it will be overridden. TreeHost sets a secure random secret key automatically.
oTree collects static files automatically on startup. Ensure your templates and static assets are included in the zip. Custom CSS and JavaScript in your _templates/ folder work normally.
| Resource | Limit |
|---|---|
| Concurrent workspaces per account | 3 |
| Project zip (compressed) | 100 MB |
| Project zip (uncompressed) | 500 MB |
| Workspace persistent storage | 1 GB |
| Workspace ID length | 3–22 characters |
These limits apply during the beta period and may change. If your research requires higher limits, contact us at [email protected].
Deployment normally takes under 60 seconds. If your workspace has been in the Deploying state for several minutes, try the Retry button. If it fails repeatedly, contact support with the workspace ID.
If you open a workspace while it's in the Starting state, you'll see a "Service Unavailable" page that auto-refreshes every 10 seconds. Wait for the workspace card to show Running before sharing the URL with participants.
Your zip likely contains a top-level folder rather than the project files directly. Re-zip with cd my-project && zip -r ../project.zip . instead of zipping the folder from outside.
Your settings.py must define SESSION_CONFIGS. This is required by all oTree 5 projects. Check that you're zipping the correct directory.
Participants must be given direct oTree session links, not the bare workspace URL (your-id.treehost.io). Generate participant links from the oTree admin panel and share those instead.
oTree's admin interface uses a separate password configured in your settings.py via OTREE_ADMIN_PASSWORD. This is independent of your TreeHost account. Set it in your project settings or use the oTree default.
Email us at [email protected]. Include your workspace ID and a description of the issue.