llms.txt
Compare with other sites' llms.txt files →# Disco, for coding agents and LLMs
This is the Disco agent skill (https://github.com/letsdiscodev/skills), followed by its reference files.
Install it into Claude Code, Codex, Cursor and others with: npx skills add letsdiscodev/skills
# Disco
Disco turns an Ubuntu 24.04 server you control into a private PaaS: zero-downtime deploys from git push or from a directory, HTTPS via Caddy, env vars, logs, volumes, cron jobs, a web dashboard and a CLI. App traffic goes straight to the server, Disco's own servers only host the dashboard.
Everything below is the `disco` CLI. For the flags of any command, run `disco <command> --help`. The full reference: https://disco.cloud/docs/cli/reference/
## The loop
1. The repo has a `Dockerfile` and a `disco.json` at its root (see the "disco.json shapes" section below).
2. `disco projects:add --name NAME --github USER/REPO` creates the project and deploys it.
3. Every `git push` deploys again (GitHub sends a webhook to the server).
4. `disco deploy:output --project NAME` shows the build and deploy log, `disco logs --project NAME` the app's logs.
## Deploy without GitHub
```bash
disco deploy --project NAME --dir .
```
Sends the directory (minus `.dockerignore`, `.gitignore` and `.git`) to the server and deploys it. The project must exist: `disco projects:add --name NAME` with no `--github`. Good for CI, other forges, or a first try before setting up a GitHub app.
## Which server
If the CLI knows a single server, commands just work. With several, add `--disco SERVER` to every command. `disco discos:list` shows them. `disco meta:info` checks the connection.
## Domains
- `disco projects:add` without `--domain` gives the project `NAME.<server host>` when the server uses a Disco-provided host (something.ondis.co) or its host has a wildcard DNS record. `--no-domain` for workers and other services that do not serve HTTP.
- Your own domain: create a CNAME (or A record) pointing at the server first, then `disco projects:add ... --domain app.example.com`, or later `disco domains:add app.example.com --project NAME`. HTTPS is automatic.
- The server's own host (disco.example.com) can never be a project domain.
## Env vars
Never in disco.json or the repo. `disco env:set --project NAME KEY=VALUE KEY2=VALUE2` (redeploys), `disco env:list --project NAME`, `disco env:remove --project NAME KEY`.
## The other things you will need
```bash
disco projects:list
disco deploy:list --project NAME # deployments, --json for scripts
disco deploy --project NAME # redeploy the latest commit
disco logs --project NAME --service web # live logs, ctrl-c to stop
disco run --project NAME "python manage.py createsuperuser" # a one-off command in the project's image
disco scale:set --project NAME web=2
disco volumes:export --project NAME --volume data --output data.tar.gz
disco volumes:import --project NAME --volume data --input data.tar.gz
disco projects:remove NAME
disco postgres:create --project NAME # a Postgres database for the project, DATABASE_URL set for you
```
## Setting up a server (only if there is none yet)
Two ways. The dashboard way: SSH into a fresh Ubuntu 24.04 server, run `curl -fsSL https://disco.cloud/install.sh | sh`, open the printed URL, log in with GitHub, then "Setup CLI Access" in the sidebar gives the `disco invite:accept URL` command to run on the dev machine. The CLI way: install the CLI on the dev machine with `curl https://cli-assets.letsdisco.dev/install.sh | sh`, then `disco init root@disco.example.com`, where `disco.example.com` is an A record for the server (not an IP, not a name you want for a project).
GitHub app, once per server, only for git push deploys: `disco github:apps:add` opens a browser to create a self-hosted GitHub app and pick the repos it may deploy. `disco github:repos:list` shows what is authorized.
## Do not
- Do not put secrets or env vars in disco.json, the Dockerfile or the repo.
- Do not SSH into the server to edit containers, files or Docker: every change goes through the CLI or dashboard, deploys are immutable.
- Do not run `disco init` on a server that already runs Disco.
- Do not guess flags: `disco <command> --help`.
## When something fails
- Build fails: `disco deploy:output --project NAME`, fix locally, push (or `deploy --dir` again).
- App up but no response: is the `web` service listening on the `port` in disco.json, on 0.0.0.0?
- Domain not working: does it resolve to the server (`dig +short app.example.com`)? HTTPS takes up to a minute the first time.
- "No disco.json": the project root needs one, see the "disco.json shapes" section below.
- More: https://disco.cloud/docs/ and the Discord https://discord.gg/7J4vb5uUwU
## Examples to copy from
See the "Example repos" section below (Node, Flask, static, Vite, Go, Rust).
# disco.json shapes
Sits at the root of the repo next to the Dockerfile. Full reference: https://disco.cloud/docs/disco-json/
## A backend (anything with a Dockerfile that listens on a port)
```json
{"version": "1.0", "services": {"web": {"port": 8000}}}
```
`web` is the reserved name: the only service that receives public HTTP traffic. `port` is what the app listens on inside the container, bind to 0.0.0.0.
## With a volume (SQLite, uploads)
```json
{
"version": "1.0",
"services": {
"web": {"port": 8000, "volumes": [{"name": "data", "destinationPath": "/data"}]}
}
}
```
Containers are ephemeral, anything not in a volume is gone at the next deploy.
## A worker sharing the image and the volume
```json
{
"version": "1.0",
"services": {
"web": {"port": 8000, "volumes": [{"name": "data", "destinationPath": "/data"}]},
"worker": {"command": "python worker.py", "volumes": [{"name": "data", "destinationPath": "/data"}]}
}
}
```
## A cron job
```json
{
"version": "1.0",
"services": {
"web": {"port": 8000},
"cleanup": {"type": "cron", "schedule": "0 4 * * *", "command": "python cleanup.py"}
}
}
```
## Migrations before the new version goes live
```json
{
"version": "1.0",
"services": {
"web": {"port": 8000, "volumes": [{"name": "db", "destinationPath": "/data"}]},
"hook:deploy:start:before": {"type": "command", "command": "python manage.py migrate", "volumes": [{"name": "db", "destinationPath": "/data"}]}
}
}
```
A failing hook aborts the deploy, the old version keeps running.
## A static site, no build step (files in `public/`)
```json
{"version": "1.0", "services": {"web": {"type": "static", "publicPath": "public"}}}
```
No Dockerfile needed.
## A static site generator (Astro, Vite, Next export, Jekyll...)
```json
{"version": "1.0", "services": {"web": {"type": "generator", "publicPath": "dist"}}}
```
The Dockerfile builds the site, Disco runs it, serves `publicPath` from inside the container.
## A prebuilt image, no Dockerfile
```json
{
"version": "1.0",
"services": {
"web": {"image": "getmeili/meilisearch:v1.13", "port": 7700, "volumes": [{"name": "meili_data", "destinationPath": "/meili_data"}]}
}
}
```
## Health check for zero-downtime deploys
```json
{"version": "1.0", "services": {"web": {"port": 8080, "health": {"command": "curl -f http://localhost:8080/health || exit 1"}}}}
```
Without it Disco waits for the port to accept connections.
## Monorepo, several Dockerfiles
```json
{
"version": "1.0",
"services": {
"web": {"port": 8000, "image": "backend"},
"worker": {"command": "node worker.js", "image": "worker"}
},
"images": {
"backend": {"dockerfile": "api/Dockerfile", "context": "api"},
"worker": {"dockerfile": "worker/Dockerfile", "context": "worker"}
}
}
```
## A raw TCP/UDP port (game server, websocket)
```json
{
"version": "1.0",
"services": {
"web": {"port": 3000},
"ws": {"command": "npx y-websocket", "publishedPorts": [{"publishedAs": 1234, "fromContainerPort": 1234, "protocol": "tcp"}]}
}
}
```
## Service fields
| field | meaning |
| --- | --- |
| `type` | `container` (default), `static`, `generator`, `cron`, `command` |
| `port` | Port the container listens on, required for `web` |
| `image` | A registry image, or a key of `images`; omitted = build the root Dockerfile |
| `command` | Overrides the image's CMD |
| `volumes` | `[{name, destinationPath}]`, same name = same data across services |
| `schedule` | Cron expression, `type: cron` only |
| `health` | `{command}` |
| `publicPath` | Folder to serve, `static` and `generator` only |
| `publishedPorts` | `[{publishedAs, fromContainerPort, protocol}]` |
# Example repos
Each has a working Dockerfile and disco.json. Copy the two files, adjust the port and the command.
- Node: https://github.com/letsdiscodev/example-node-site
- Flask / Python: https://github.com/letsdiscodev/example-flask-site
- Static files: https://github.com/letsdiscodev/example-static-site
- Vite (built on every push, served statically): https://github.com/letsdiscodev/example-vite
- Go: https://github.com/letsdiscodev/example-go-site
- Rust: https://github.com/letsdiscodev/example-rust-site
More frameworks: https://disco.cloud/docs/frameworks/