Start here
Getting started
Paste a link or describe what you need. Setup writes a recipe, runs it as a one-hour trial and keeps it running if you want.
On this page
Setup turns a link or a sentence into software that runs. You paste a GitHub repository, a Hugging Face Space or an install guide, or you write what you need, like "a photo backup for my family". Setup works out how to run it, starts it in a sandbox and gives you a link to open it.
Every new app starts as a free trial that removes itself after 60 minutes. If you like it, you keep it, and Setup looks after it from then on. You don't install anything, and nothing runs on your own computer.
What you can paste
| You paste | Example | What Setup does |
|---|---|---|
| A Git repository | https://github.com/louislam/uptime-kuma | Reads its setup.json, Compose file or Dockerfile, or the usual layout of its language |
| A link to one file | https://github.com/owner/app/blob/main/compose.yaml, a raw URL, a gist | Reads that file, together with the repository around it when there is one |
| A Docker Compose file | The contents of a compose.yaml, with its .env if it has one | Turns its services into a recipe |
docker run commands | docker run -d -p 8080:80 traefik/whoami:v1.10 | Turns one or several commands into one app |
| An image | nginx:1.27, ghcr.io/owner/app:1.2 or a Docker Hub page | Reads the ports and volumes the image declares from its registry, without downloading it |
| A Dockerfile | A Dockerfile that copies no files of its own | Builds it. One that copies files needs the repository it lives in |
| An app store definition | A CasaOS, Umbrel, Runtipi or Cosmos app, or a Portainer template | Turns it into a recipe and opens the port the store would open |
| Kubernetes manifests | A Deployment with its Service, volume claim, ConfigMap and Secret | Turns the parts that make sense for one app into a recipe and lists the rest |
| A Hugging Face Space | https://huggingface.co/spaces/owner/name | Reads how the Space is set up |
| A docs page | An install guide with a docker run or Compose snippet | Turns the snippet into a recipe and suggests repositories the page links to |
| A sentence | "a wiki for my team" | Suggests software that fits |
| A recipe | The contents of a setup.json | Uses it as it is |
GitLab and other Git hosts work too. owner/name on its own means a GitHub repository; if there is none, Setup reads the Docker Hub image of that name. Links to language models on Hugging Face are the exception: Setup runs apps, not language models. The FAQ explains what to do instead.
You can paste a chat answer or a README excerpt as it is. Setup takes the code blocks out of the text around them and reads a Compose file and its .env together. Pasted text can be up to 100,000 characters.
Everything you paste is read as data. Setup drops what a recipe cannot run safely (privileged mode, host folders, the Docker socket, host networking, added capabilities) and lists each thing it dropped under What Setup noticed. It never downloads an image or runs anything while it reads.
In the paste box, Enter runs a single line. Once the text has several lines, Enter adds a line like in any editor, and ⌘ Enter (Ctrl Enter on Windows and Linux) runs it. The box tells you what it recognized while you type, and after the analysis the page says what Setup found, for example "A Docker Compose file with 3 services".
Step by step
1. Paste
Sign in and open your dashboard at /dashboard. In the detailed view, paste into the box under "What do you want to run?" and press Run it. In the simple view, tell the assistant what you need, or open Add an app and pick an app by what it's for.
You can also start from the public catalog at /catalog (Run this on a project's page), or from a "Run on Setup" button in a project's README.
2. Setup reads it and writes a recipe
Setup fetches what you pasted and reads it like a document. Nothing is installed or run at this stage. You can watch the steps of the analysis as they happen.
The result is a recipe: a short file called setup.json that says which programs run, which settings they need and how Setup checks that the app works. The page shows it in plain words under What runs, and as a file under Recipe JSON if you want to edit it. Confidence says how sure Setup is, and What Setup noticed lists anything worth checking before you start.
A setup.json in the repository comes first, then a curated recipe from the Setup catalog, then what Setup detects on its own. If Setup finds nothing it can host, it says so and suggests something to run instead. Recipes has the details.
3. Start a trial
Fill in the settings the app needs. Passwords and secret keys marked "Generated if left empty" can stay empty; Setup creates them. Under How long, choose Try it, then press Deploy.
A runner picks up the app and starts it in a sandbox. The page shows each phase: waiting for a runner, preparing the sandbox, pulling images or building, starting services and running checks. With a ready-made image this often takes a minute or two. Building from source takes longer. When the checks pass, you get the app's address.
Apps run on your workspace's own runner when one is online, otherwise on Setup Cloud. If no runner is available, the app waits in the queue until one connects. See Runners to connect your own machine.
4. Keep it
A trial runs for 60 minutes. Ten minutes before the end, Setup sends you an email. When the time is up, Setup removes the app and everything stored in it.
To keep the app, press Keep it on its page any time before the trial ends. A kept app stays up until you remove it. Setup checks its health, emails you when it goes down, and you can turn on automatic updates and scheduled backups for it. Keep it running covers all of that.
If you already know you want an app, choose Keep it running instead of Try it before you deploy.
Where to find your apps
In the detailed view, Apps at /dashboard/apps lists everything in the workspace, with tabs for Active, Trials, Failed and Ended. Open an app to see its address, logs, health, backups, recipe and settings.
In the simple view, Your apps on the home page shows each app as a card with a plain status, such as "Running" or "Something went wrong", and how much trial time is left. Open opens the app itself. Ask about this hands the question to the assistant.
Team workspaces have the same pages under their own address, for example /dashboard/your-team/apps.
Limits worth knowing
- A trial lasts 60 minutes and can't be extended. Keep the app instead.
- You can start 30 analyses an hour. Pasted text can be up to 100,000 characters.
- Setup doesn't host language models. Apps that use one get the address and key of a hosted model API, such as OpenRouter, as a setting.
- Removing an app deletes it and its data. It can't be undone.
Next steps
- Simple and detailed view: pick how much detail you see.
- The assistant: what you can ask it to do.
- Keep it running: updates, backups, alerts and status pages.