Projects & Deployments

Projects

A project is the primary unit of identity in deplo.sh. It holds:

• A globally unique slug that determines the public subdomain
• A pointer to the live deployment (the version currently being served)
• Optional custom domain configuration
• Members and access token assignments

Creating a project

Projects are auto-created when you first deploy to them:

deplo deploy report.html --project my-report
# ✔ Project "my-report" created
# ✔ Deployed to https://my-report.deplo.sh

Or create one explicitly:

deplo projects create "My Report" --slug my-report --type static_file

Project slugs

Slugs are globally unique across the entire platform. If your desired slug is taken, the CLI will suggest alternatives or let you pick a different one.

Valid slug format: lowercase letters, numbers, and hyphens. Max 63 characters.

Deployments

A deployment is an immutable snapshot of content. Each time you deploy to a project, a new deployment version is created and automatically made LIVE.

Deployment lifecycle

LIVE → promoted → still LIVE (version increments)
LIVE → new deploy → previous becomes ARCHIVED, new is LIVE
ARCHIVED → promote → becomes LIVE again (rollback)
TTL expires → ARCHIVED files deleted from storage

Deployment types

TTL (time-to-live)

Each deployment has a TTL that determines when it is automatically archived:

Rolling back

Promote any archived deployment to make it live again:

# List versions
deplo deployments list my-report

# Roll back to a specific version
deplo deployments promote my-report dep_abc123

The project URL instantly serves the promoted version — no DNS change needed.

Gate (access control)

Every project has a gate that controls how visitors access your content. There are three gate types:

Setting a gate via CLI

# Password-protect a project
deplo projects update my-project --gate password --password s3cr3t

# Require email submission (lead capture)
deplo projects update my-project --gate email

# Remove gate (make public)
deplo projects update my-project --gate none

Setting a gate via REST API

PATCH /projects/:projectId
Content-Type: application/json

{
  "gate_type": "email"
}

PATCH /projects/:projectId
Content-Type: application/json

{
  "gate_type": "password",
  "password": "s3cr3t"
}

The gate page

When a gate is active, visitors are shown a branded gate page before they can access your deployment. The gate page is served by the Router at the same URL as your content — no redirects, no separate domain.

• Password gate — visitors enter the password and are granted access for the browser session.
• Email gate — visitors enter their email address. The email is encrypted and stored as a lead. Access is granted immediately after submission.

Leads (email gate)

When gate_type is email, every unique visitor email is stored as a lead. Leads are:

• Encrypted at rest — stored with AES-256 encryption, decrypted only when you retrieve them via the API or dashboard
• Timestamped — each lead records when the email was first submitted (captured_at)
• Deduplicated — the same email is only recorded once per project

View leads in the dashboard: Go to Leads in the sidebar — you can filter by project, search by email, and paginate through all captured leads.

View leads via CLI:

deplo leads list my-project
deplo leads list my-project --search "@acme.com"
deplo leads export my-project --format csv --output leads.csv

View leads via REST API:

GET /projects/:projectId/gate/leads?page=1&limit=20

View leads via MCP:

Use the gate_list_leads tool with the project ID to retrieve leads.

Storage and limits

Storage is calculated as the sum of all live and archived deployment file sizes.

Serving a deployment

When a visitor accesses https://my-report.deplo.sh:

1. Cloudflare resolves DNS → terminates TLS → forwards to the Router service
2. Router extracts the subdomain (my-report)
3. Redis cache lookup: slug → live deployment ID + gate config (cache hit ≈ 1ms)
4. Gate check — if gate_type is password, visitor must provide the correct password; if gate_type is email, visitor must submit their email (stored as a lead) before continuing
5. File streamed from Cloudflare R2 with correct Content-Type
6. Cloudflare CDN caches the response at edge

What's next?

• Quickstart — deploy your first file in under 60 seconds
• Custom Domains — attach a branded domain to your project
• Core Concepts — understand the full resource hierarchy
• CLI Reference — manage projects, gates, and leads from the terminal
• REST API — the HTTP API for programmatic project management
• MCP Server — use gate_list_leads and projects_update from Claude or Cursor