DOCSEARCHbyAlgolia
Submit Docs

Disco for Coding Agents and LLMs

website·Indexed 33 days ago

https://disco.cloud/docs/

A tool and agent skill designed for coding agents and LLMs, including a framework for integration and reference files for implementation.

Tokens
1.5K
Snippets
9
Records
10
Agent score
19%

What's inside Disco

  1. Set up a Disco server

    There are two ways to initialize a Disco server on a fresh Ubuntu 24.04 instance:

    1. Dashboard Method: SSH into the server, run the installation script, and follow the printed URL to log in via GitHub. Then, use the 'Setup CLI Access' sidebar option to get the disco invite:accept command for your local machine.
    2. CLI Method: Install the CLI on your local machine and run disco init with the server's A record (hostname).

    Important: Do not run disco init on a server that already has Disco installed.

    # Dashboard method (on server)
curl -fsSL https://disco.cloud/install.sh | sh

# CLI method (on local machine)
curl https://cli-assets.letsdisco.dev/install.sh | sh
disco init root@disco.example.com

  2. Deploy a project with Disco

    Disco requires a Dockerfile and a disco.json at the root of the repository.

    GitHub Deployment: Use disco projects:add with the --github flag. Subsequent git push events will trigger automatic redeploys via webhooks.

    Manual/CI Deployment: Use disco deploy --dir . to send a local directory to the server. The project must first be created using disco projects:add --name NAME without the --github flag.

    # Deploy from GitHub
disco projects:add --name my-app --github user/repo

# Deploy from local directory
disco projects:add --name my-app
disco deploy --project my-app --dir .

  3. Install the Disco agent skill

    Install the Disco agent skill into AI coding tools such as Claude Code, Codex, and Cursor using the following command:
    npx skills add letsdiscodev/skills

  4. Configure static sites and prebuilt images in disco.json

    Disco supports static sites (without Dockerfiles) and prebuilt images from registries.
    // Static site (files in public/ folder, no Dockerfile needed)
{"version": "1.0", "services": {"web": {"type": "static", "publicPath": "public"}}}

// Static site generator (Dockerfile builds, Disco serves dist folder)
{"version": "1.0", "services": {"web": {"type": "generator", "publicPath": "dist"}}}

// Prebuilt image (no Dockerfile)
{
  "version": "1.0",
  "services": {
    "web": {
      "image": "getmeili/meilisearch:v1.13",
      "port": 7700,
      "volumes": [{"name": "meili_data", "destinationPath": "/meili_data"}]
    }
  }
}

  5. Configure project services with disco.json

    The disco.json file defines the project structure. The web service is a reserved name for the only service receiving public HTTP traffic. All apps must bind to 0.0.0.0.
    {
  "version": "1.0",
  "services": {
    "web": {
      "port": 8000,
      "volumes": [{"name": "data", "destinationPath": "/data"}],
      "health": {"command": "curl -f http://localhost:8000/health || exit 1"}
    },
    "worker": {
      "command": "python worker.py",
      "volumes": [{"name": "data", "destinationPath": "/data"}]
    },
    "cleanup": {
      "type": "cron",
      "schedule": "0 4 * * *",
      "command": "python cleanup.py"
    },
    "hook:deploy:start:before": {
      "type": "command",
      "command": "python manage.py migrate",
      "volumes": [{"name": "db", "destinationPath": "/data"}]
    }
  }
}

  6. Configure monorepos and raw TCP/UDP ports in disco.json

    Use the images key for monorepos with multiple Dockerfiles, and publishedPorts for non-HTTP traffic.
    // Monorepo configuration
{
  "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"}
  }
}

// Raw TCP/UDP port (e.g. WebSockets)
{
  "version": "1.0",
  "services": {
    "web": {"port": 3000},
    "ws": {
      "command": "npx y-websocket",
      "publishedPorts": [{"publishedAs": 1234, "fromContainerPort": 1234, "protocol": "tcp"}]
    }
  }
}

  7. Manage project domains and HTTPS

    Disco provides automatic HTTPS via Caddy.

    • Default: If no domain is specified, projects get NAME.<server host> (if using a Disco-provided host or wildcard DNS).
    • Custom Domain: Create a CNAME or A record pointing to the server first, then add the domain during project creation or later via the CLI.
    • No Domain: Use --no-domain for workers or non-HTTP services.
    • Constraint: The server's primary host (e.g., disco.example.com) cannot be used as a project domain.
    # Add project with custom domain
disco projects:add --name my-app --domain app.example.com

# Add domain to existing project
disco domains:add app.example.com --project my-app

  8. Troubleshoot Disco deployments

    Common failure scenarios and resolutions:

    • Build Fails: Check logs with disco deploy:output --project NAME.
    • No Response: Ensure the web service is listening on the port specified in disco.json and bound to 0.0.0.0.
    • Domain Issues: Verify DNS resolution with dig +short app.example.com. Note that HTTPS can take up to a minute to initialize.
    • Missing Config: Ensure disco.json exists at the project root.

  9. Manage environment variables in Disco

    Environment variables must never be stored in disco.json or the git repository. Use the CLI to manage them. Setting a new variable triggers a redeploy.
    # Set variables (triggers redeploy)
disco env:set --project NAME KEY1=VALUE1 KEY2=VALUE2

# List variables
disco env:list --project NAME

# Remove a variable
disco env:remove --project NAME KEY

  10. Common Disco CLI operations

    Essential commands for managing projects, logs, scaling, and databases.
    disco projects:list
disco deploy:list --project NAME          # List deployments (--json for scripts)
disco deploy --project NAME               # Redeploy latest commit
disco logs --project NAME --service web   # Live logs
disco run --project NAME "command"        # Run one-off command in container
disco scale:set --project NAME web=2      # Scale service
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      # Create Postgres DB (sets DATABASE_URL)