Core Concepts
Understand the key building blocks of deplo.sh.
Resource hierarchy
Workspace
├── Members (owner, admin, viewer)
├── Tokens (workspace-scoped API keys)
└── Projects
├── Settings
│ ├── slug → weekly-report (globally unique)
│ ├── custom_domain → reports.acme.com
│ ├── gate_type → none | password | email
│ └── default_ttl → 7d | 30d | forever
├── Tokens (project-scoped API keys)
├── Gate Leads (email addresses captured by the email gate)
└── Deployments
├── dep_v1 (archived)
├── dep_v2 (archived)
└── dep_v3 (LIVE) → https://weekly-report.deplo.shKey concepts
Workspace
The top-level tenant. Maps to an organisation or individual account. Owns projects, billing, and API tokens.
Project
A named deployment target. Has a globally unique slug (e.g. weekly-report → weekly-report.deplo.sh), a live deployment pointer, and optional custom domain settings.
Every time you deploy to a project, the project URL instantly serves the new content. Rolling back is just promoting an older deployment — no DNS change required.
Deployment
An immutable snapshot of content associated with a project. Each deploy creates a new deployment version. Only one deployment is LIVE at any time; others are ARCHIVED but retained.
Custom Domain
A CNAME record pointing to the platform (proxy.deplo.sh). Attaches to a project — not to a specific deployment — so domain ownership survives rollbacks. TLS certificates are provisioned automatically via Cloudflare SSL for SaaS.
Gate
A gate controls visitor access to a project's deployed content. Three modes:
| Type | Behaviour |
|---|---|
none | Publicly accessible — no gate (default) |
password | Visitors must enter a password; access is granted for the browser session |
email | Visitors must submit their email address; the email is stored as a lead and access is granted |
The gate is served inline at the project URL by the Router — no redirects or subdomains.
Gate Lead
A lead is an email address captured when a visitor passes through an email gate. Leads are:
- Encrypted at rest (AES-256) and decrypted on retrieval
- Timestamped — the
captured_atfield records when the email was first submitted - Deduplicated — the same email is recorded only once per project
View leads in the dashboard under Leads, via the CLI (deplo leads list), the REST API (GET /projects/:id/gate/leads), or the MCP gate_list_leads tool.
Access Token
A scoped API key (sk_live_...). Can be:
- Workspace-level — all projects in the workspace
- Project-level — a single project only
Tokens support four permission scopes: deploy, read, delete, admin.
TTL (Time-to-Live)
The lifetime of a deployment before it is automatically archived. Options:
| Value | Duration |
|---|---|
1h | 1 hour |
24h | 24 hours |
7d | 7 days (default) |
30d | 30 days |
forever | No expiry (paid plans) |
Archived deployments have their files removed from R2 but their metadata is retained.
Deployment types
| Type | Description | Example |
|---|---|---|
static_file | Single file: HTML, PDF, JSON, CSV, PNG, etc. | Agent publishes a generated HTML report |
static_site | Multiple files with an entry point (index.html) | Agent builds a full HTML+CSS+JS dashboard |
json_api | JSON blob exposed as a read-only REST endpoint | Agent produces structured data accessible via GET |
Global slug uniqueness
Project slugs are unique across the entire platform — not just within a workspace. This means:
reports.acme.comandreports.othercorp.comcan both point to deplo.sh- Slug collisions between workspaces are impossible
- The subdomain is claimed permanently when a project is created
If a slug is taken, the API returns a 409 Conflict with suggestions. The CLI auto-appends a suffix to find an available slug.
What's next?
- Quickstart — deploy your first file in under 60 seconds
- What is deplo.sh? — high-level platform overview
- Projects & Deployments — managing projects, versions, and rollbacks
- REST API — the HTTP API that powers all integrations