DeployMill docs
The same guides and references your agent reads, browsable here. Every page is also an MCP resource your agent can fetch or search with search_docs.
Introduction
The one-page mental model: the neutral, agent-safe control plane over compute, database, domain, secrets, source, and object storage — driven entirely by MCP tools, neutral across provider backends, with the guardrails to hand an agent production. What it does, what it deliberately doesn't, and how the pieces fit.
Connect an MCP client to deploymill and go from nothing to a live app: authenticate, call start_project, push code, and find the URL. The first thing a new human or agent should read.
The single copy-paste prompt a newly-connected user hands their agent to get a live example app. The agent reads the getting-started + guides resources, calls start_project, shows the core loop (push_files, create_preview, get_logs, rollback), and leaves a running app — no dashboard clicking. Includes how to tweak it (stack, your own idea, go faster).
The main product is the MCP tools — this is how a human wires deploymill into their agent. One-time setup for Claude Code, Claude Desktop/claude.ai, Cursor, VS Code, and any other remote-MCP client: paste the endpoint URL, run the OAuth sign-in, done.
The at-a-glance map of everything DeployMill can do and which surface drives it: a per-capability matrix with MCP / API / UI columns across the whole deploy lifecycle (projects, deploy, previews, domains, env vars, secrets, source, object storage, backups) plus the API-first workspace-administration surface. Shows the agent-first approach in one view — MCP is the most complete column for shipping apps; workspace admin is deliberately off the agent surface.
The operational reference for pricing and limits under uptime billing: your apps sleep when idle so you don't pay for idle time, the three relationships (Explore no-card, Builder card with the `max($10, usage)` floor that includes your first $10 of usage, Enterprise contract), free + unlimited seats, the spend cap, the dunning ladder when a payment fails, and the structured `upgrade_required` / `cap_reached` / `*_limit_reached` error codes an agent sees — plus get_account for live spend and headroom.
The first place to look when something goes wrong: the deploy/build failure loop, common error codes and what they mean, the health-gate and DNS gotchas, and how to escalate when the docs run out.
How to reach DeployMill and where to send each kind of request: email-based support ([email protected] + the /account/support dashboard page) with the context that gets a fast answer, security vulnerabilities (security@ + the disclosure policy), and the privacy/data/legal/abuse contact addresses. The unauthenticated place pre-signup visitors and agents can find a way to reach us.
Building your app
The fastest path to a working app: pick a curated DB-backed starter (kanban, todo, link-in-bio, event-rsvp) with list_templates, scaffold it with start_project (managed Postgres + DATABASE_URL are provisioned before the first deploy — no extra reconcile), then remix it live by editing the app source and redeploying. Covers the Explore free-floor (state in managed Postgres only; no volumes/object-storage/egress; subdomain-only) and the worked 'grow it into a real app' upgrade path on Builder — add a third-party API key the agent never sees (request_secret/bind_secret) and lock an admin route (set_app_protection), e.g. a waitlist that collects emails and a protected admin page that mass-mails them.
Layout, PORT contract, Dockerfile conventions, common modifications, and what NOT to do when modifying a deploymill-managed Node app scaffolded from the `node` template.
Layout, host/port contract, Dockerfile conventions, common modifications, and what NOT to do when modifying a deploymill-managed Python app scaffolded from the `python` template.
Layout, Dockerfile conventions, what the static stack supports and doesn't (no env at runtime, no DB, no runtime mutation), and how to add assets or SPA routing.
deploymill's paved road for Node apps: the libraries the template and database guide already commit to (Hono, pnpm, pg + node-pg-migrate), recommended-but-optional picks for auth/validation/TypeScript, what deploymill has no opinion on, and the `.deploymill/conventions.md` project override. Read before writing non-trivial application code.
deploymill's paved road for Python apps: the libraries the template and database guide already commit to (FastAPI + uvicorn, uv, psycopg + alembic), recommended-but-optional picks for validation/auth/concurrency, what deploymill has no opinion on, and the `.deploymill/conventions.md` project override. Read before writing non-trivial application code.
Configuration & deployment
Full schema for the project config file plus the edit-file-then-reconcile workflow: domain, mounts, rollback, database, dryRun/prune flags, and what reconcile does NOT do.
The playbook for adopting a repo deploymill never scaffolded — e.g. an app written in Cursor with no .deploymill/project.json and no Dockerfile: get the code onto GitHub, run import_repo (which scaffolds the config), read the readiness report, write the Dockerfile deploymill requires to build (PORT/EXPOSE/0.0.0.0/healthz contract + per-stack sketches), fix the flagged env/database/persistence gaps, and deploy.
Where a project's files live and how the storage backend is modeled as a provider-neutral primitive: the file tools (push_files/get_file/list_files), the optional `source` block in .deploymill/project.json, and how a non-GitHub backend (e.g. self-hosted Gitea) would slot in without changing any tool.
Download any project's full source as a zip from the Code page — the portability/takeout path, since repos live under deploymill's GitHub account. Covers what's in the archive (code + Dockerfile + .deploymill/project.json), what's deliberately out (database contents, secret values, volumes), the admin/owner-default `code.export` capability, and the audit trail.
How `set_env_vars` / `list_env_vars` / `delete_env_vars` work: merge-vs-replace semantics, `${{project.X}}` template references, the redeploy-required rule, and the previews-share-prod-env consequence.
How to store org-scoped secrets in the encrypted vault (`request_secret` browser hand-off — values never cross the agent) and get them into apps — `bind_secret` for one-offs or the `secrets` array in `.deploymill/project.json` + `reconcile_project` for config-as-code. Covers what encryption does and doesn't protect, the redaction guarantees, and wiring an app's Google OAuth (client id/secret + redirect URI).
The health-endpoint contract: every web app exposes one endpoint (default /healthz) that returns 200 iff fully healthy; deploy/rollback/get_app (its health block) and auto-rollback all key off it (200 = good, anything else = roll back). Covers the `health` block in .deploymill/project.json (path/retries/intervalMs/timeoutMs), strict vs lenient probe semantics, the N-consecutive-failure rule, the 404 fallback, the orchestrator-level health gate, and how to write real readiness checks into the handler. Read before relying on auto-rollback.
Enabling rollback via `.deploymill/project.json`, performing an image-swap rollback with `list_deployments` + `rollback`, what rollback does NOT cover (migrations, env vars, data), and when to use it vs forward-fix.
How to run time-triggered work (a daily digest email, a nightly webhook) on deploymill: first decide whether the work is actually lazy (derive it on read — no scheduler needed) or genuinely side-effecting (needs a scheduler). For the side-effecting case, declare a `schedules: [{ name, cron }]` block in `.deploymill/project.json`, then implement the `/_system/tick` receiver (Node + Python snippets) that verifies the `DM_SCHEDULE_TICK_SECRET` bearer token and dispatches to your handler. Covers the at-least-once / 'derive, don't fire' idempotency rule, the platform run-lock, and why the secret never reaches the agent.
How to read build/deploy logs (`source: "build"`) and runtime container stdout/stderr (`source: "runtime"`) with `get_logs` — `tail`/`grep`/`level`/`since` filtering, when to use which source, and the failed-deploy debugging loop.
Domains, previews & access
The end-to-end custom-domain playbook an agent follows to attach a domain the user owns: the one-time DNS TXT ownership proof (`domain_verification_required`), pointing the host at the ingress (CNAME for a subdomain / A record for an apex, DNS-only/unproxied), the coded errors each path returns (carrying the exact record to create), the automatic Let's Encrypt cert + propagation caveat, the `attach_domain` vs `domains.custom`+reconcile paths, and detaching. Read before instructing a user on custom-domain DNS.
How PR previews are created, hostname derivation (auto-generated vs wildcard-domain-base), and the shared-prod-database gotcha. Read this before doing destructive migrations on a PR branch.
First-class staging/QA environments as PERMANENT previews tagged with `environmentName`. How to create one via create_preview (and why it forces the preview permanent), the `environment_name_conflict` uniqueness guard, declaring an `environments` block in project.json for reconcile_project to ensure idempotently, the standard-quota note, and teardown via delete_app.
How to gate an app's site with `set_app_protection`: choosing HTTP Basic Auth vs organization auth (only signed-in organization members; legacy alias `mode: "workspace"`), org-wide vs selected-members access, protecting the whole site vs serving specific public paths in front of a gated app (the `publicPaths` carve-out), the one-time bypass token for CI/automation and health probes, the reserved /.deploymill/auth/* path, the CORS/programmatic-access caveat, persisting protection in .deploymill/project.json, and the fail-closed posture. Read before protecting staging/internal sites.
Best practices for adding user accounts / login to a deploymill-managed app: the four platform facts (sessions in Postgres not on the ephemeral disk, host-pinned base URL per environment, signing/OAuth secrets through the vault, Secure cookies need HTTPS), the Node paved road (Better Auth on the managed Neon DB), the Python and hosted-IdP equivalents, and per-preview auth wiring (`${PREVIEW_URL}` base URL + OAuth redirect URIs).
Wire Clerk as your app's external identity provider for user login / accounts: deploymill operates nothing here — it records the choice in the `auth` block of .deploymill/project.json and hands off the Clerk secret values (CLERK_SECRET_KEY, CLERK_PUBLISHABLE_KEY) via set_env_vars / request_secret so the agent never sees them. Covers the env-var contract, the secret hand-off, an app-side SDK snippet, and the reconcile `auth_secret_missing` presence-check.
Wire Auth0 as your app's external identity provider for user login / accounts: deploymill operates nothing here — it records the choice in the `auth` block of .deploymill/project.json and hands off the Auth0 secret values (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET) via set_env_vars / request_secret so the agent never sees them. Covers the env-var contract, the secret hand-off, an app-side SDK snippet, and the reconcile `auth_secret_missing` presence-check.
Wire Supabase Auth as your app's external identity provider for user login / accounts: deploymill operates nothing here — it records the choice in the `auth` block of .deploymill/project.json and hands off the Supabase values (SUPABASE_URL, SUPABASE_ANON_KEY) via set_env_vars / request_secret so the agent never sees them. Covers the env-var contract, the secret hand-off, an app-side SDK snippet, and the reconcile `auth_secret_missing` presence-check.
Wire WorkOS (AuthKit) as your app's external identity provider for user login / accounts: deploymill operates nothing here — it records the choice in the `auth` block of .deploymill/project.json and hands off the WorkOS secret values (WORKOS_API_KEY, WORKOS_CLIENT_ID) via set_env_vars / request_secret so the agent never sees them. Covers the env-var contract, the secret hand-off, an app-side SDK snippet, and the reconcile `auth_secret_missing` presence-check.
Databases
Step-by-step playbook an agent follows after `reconcile_project` provisions a Postgres database for a Node/Hono app: add pg, build a pooled DB module, add a /db health route, scaffold node-pg-migrate, and run migrations at container start.
Step-by-step playbook an agent follows after `reconcile_project` provisions a Postgres database for a Python/FastAPI app: add psycopg + alembic, build a pooled DB module, add a /db health route, scaffold migrations, and run them at container start.
How an agent reads a managed database's data without ever seeing the connection string: `describe_database` for the schema (tables/columns/indexes/approx row counts, never row values — free on all plans), and `query_database` for a single read-only SQL query (single statement, 1000-row cap, read-only transaction + statement timeout, secret-named-column redaction, every call audited — paid `directDataAccess` + an org governance toggle). Works on prod and preview apps, over MCP and REST /api/v1. Covers each tool's coded errors.
The data-preserving, six-step playbook for moving a deploymill app from one managed-database backend to another (e.g. SQLite → Postgres/Neon) on the SAME app without losing data: why the `conflict-provider-change` guard blocks an in-place swap (and why deleting the app is the wrong fix because it drops volumes), export-first, retiring the old managed-DB record via a pruning reconcile that re-declares domains/mounts so they survive, provisioning the new backend, porting the driver/dialect (the one-way-door rewrite), and importing the rows with ids + sequences preserved. Read before changing `database.provider` on a provisioned app.
How an app's managed database is backed up and how to recover it: automatic per-org scheduled backups, `create_backup` to snapshot on demand before a risky migration, `list_backups` to see restore points, and `restore_backup` to replay one into the live DB (dry-run first, then a confirm-echo of the applicationId — it overwrites live data, so stop_app first). Covers what's restorable (internal-postgres only; Neon/Supabase self-manage; tenant volumes are an operator runbook for now). Read before recovering lost/corrupted data.
Storage
When and how to give an app persistent disk: choosing a volume vs the managed database, declaring named-volume `mounts` in .deploymill/project.json and reconciling them, the write-under-mountPath rule, why volumes are per-app (no shared volumes — share via a service), how previews get their own fresh volume, and removing/renaming a volume. Read before persisting files to disk.
Step-by-step playbook an agent follows after `reconcile_project` provisions an R2 bucket for a Node/Hono app: add @aws-sdk/client-s3, build an S3 client from the injected S3_* env vars (R2 endpoint + forcePathStyle), upload/list/serve objects, and what NOT to do (don't park blobs on a volume, don't commit credentials).
Step-by-step playbook an agent follows after `reconcile_project` provisions an R2 bucket for a Python/FastAPI app: add boto3, build an S3 client from the injected S3_* env vars (R2 endpoint + path-style addressing), upload/list/serve objects, and what NOT to do.
How to point an app's object storage at your own S3-compatible store instead of deploymill's managed R2 (DET-835): register the store once per org in the dashboard (an admin enters endpoint/region/bucket/keys — the agent never sees them; a put/get/delete probe validates on connect and picks per-app-bucket vs shared-bucket key-prefix isolation), then select it per app with `storage: { provider: "s3", connection: <id> }` in .deploymill/project.json. Includes click-by-click provider setup recipes for AWS S3 (bucket + IAM user + the exact scoped policy the probe needs — fixes the 403 AccessDenied on connect) and Cloudflare R2 (bucket + Object Read & Write API token, region auto), plus MinIO/B2 path-style notes. Covers what env vars the app receives (S3_*, plus S3_PREFIX in prefix mode), how previews behave, and the new-objects-only cutover when switching stores.
API
Account & team administration
How to run a deploymill org as a team from the /account/org dashboard: inviting teammates (single-use 7-day links), the owner/admin/member role capability matrix in plain language, changing roles and removing/leaving members, the last-owner rule, and seats (free and unlimited on every plan under uptime pricing).
Enterprise SSO for your org: how connections are operator-managed (OIDC/SAML, no self-serve, IdP secrets server-side only), domain-based auto-join (new users land as member), SSO enforcement (blocking password/Google for claimed domains), an Okta OIDC setup walkthrough (issuer, client id/secret, the /api/auth/sso/callback redirect URI, claimed domain), and the read-only /account/org/sso status page.
What each org role (owner, admin, member) can and cannot do: deploy-lifecycle actions (all roles), workspace administration (admin/owner), compliance exports (admin/owner), and the last-owner guard that prevents orgs becoming ownerless.
The in-product upsell page every `upgrade_required` gate points an agent at (DET-631): what the free Explore tier contains and its limits (1 curated-template app, no persistent storage, no custom domains / REST API / object storage / custom templates / arbitrary import), the full set of capabilities a card lifts on at once on the $10/mo Builder plan (a $10 minimum that includes your first $10 of metered uptime usage), the path to Enterprise, and the EXACT next step — the agent explains what unlocks and hands the human the upgrade link, never touching the card itself.
Trust & security
The trust hub: deploymill's security posture (the zero-readback secret vault, hard tenant isolation, OAuth + PKCE auth, the agent-safety guardrails, encryption at rest and in transit), compliance status, data-privacy pointers, the shared-responsibility framing, how to report a vulnerability, and an index of every policy.
Exactly what a connected AI agent can and cannot do on deploymill: the capability table, the guardrails (never sees secret values, never leaves its workspace, never gets infra credentials, preview isolation, health-gated auto-rollback, dry-run reconcile, append-only audit trail), what stays human-only, the customer's responsibilities, and how to revoke access.
The division of security duties between deploymill (host/Kubernetes platform, tenant isolation, control-plane security, the secrets vault, platform availability) and the customer (their app code and data, what they instruct their agent to do, application-level security, DNS, and AUP/compliance of their own app).
How to report a security vulnerability to deploymill: scope, the safe-harbor commitment for good-faith research, rules of engagement (no other-tenant data, no DoS, coordinated disclosure), how to report ([email protected]), our response process, out-of-scope findings, and the published security.txt.
The maintained subprocessor / data-flow inventory for the default managed stack: which third parties (Neon, Supabase, GitHub, Cloudflare R2, Resend/SES, Google) receive what data categories, for what purpose, and the deployment-dependent caveats — for vendor-management, DPA, and GDPR Article 28 review.
Legal & policies
The master agreement governing use of deploymill: the service, accounts & workspaces, customer content & ownership, acceptable use, fees, suspension & termination, warranties & liability, and that the human account owner is responsible for what their connected agent does.
What personal data deploymill collects and why, the controller-vs-processor split (controller for account/identity data, processor for customer app data), legal bases, sharing & subprocessors, international transfers, retention, security, and your GDPR/CCPA rights and how to exercise them.
What you may not deploy or run on deploymill: prohibited content and activities (malware, phishing, abuse, resource/compute abuse, attacking third parties, circumventing tenant isolation), the human owner's accountability for their agent's actions, enforcement, and how to report abuse.
How deploymill uses cookies and local storage — primarily the strictly-necessary session/auth cookies that sign-in depends on — plus third-party sign-in cookies, how to control them, and Do Not Track.
How long deploymill keeps each kind of data and how deletion works: the retention table (accounts, secrets, app/preview metadata, deployed-app data, audit logs, backups), the self-serve account/app deletion path and grace window, data-subject erasure, and how deletion propagates to backups.
deploymill's GDPR Article 28 Data Processing Agreement: roles, processing scope, customer instructions, processor obligations, subprocessor authorization (incorporating the maintained subprocessor list), international transfers (SCCs), technical & organizational measures, breach notification, audit rights, return/deletion, and the processing annexes.
The uptime commitment for the deploymill control plane (MCP API + dashboard), the service-credit table, what counts as downtime and what's excluded (scheduled maintenance, customer app code / agent actions, subprocessor outages, force majeure), and how to claim a credit.