Ezdeploy

English · 简体中文

EZdeploy is an open-source, agent-native personal application deployment center. Install its deployment Skill once, save one revocable persistent key, and then tell Codex, WorkBuddy, or another coding agent to “deploy to my app center.” The agent analyzes the project, previews the exact deployment plan, waits for confirmation, publishes it to your Cloudflare account, verifies application health, and returns a live URL on your own domain.

The application center includes English and Simplified Chinese interfaces. Open /en for English or use the language switch on any page; both languages share the same administrator account, applications, deployment keys, and AI provider configuration.

Why EZdeploy

• One sentence to production. Install once, save one key — every later deploy starts from a sentence, not a toolchain.
• You confirm before anything ships. Every deployment previews provider, bindings, access scope, and risks, and execution is bound to the confirmed plan digest.
• Your infrastructure, your credentials. Everything runs in your own Cloudflare account. Provider credentials live as Worker secrets and never enter an application repository or an agent prompt.
• Built to be found by agents. The canonical workflow is discoverable through agent.md, the installable Skill, skill.md, agents.md, llms.txt, /.well-known/ezdeploy.json, and openapi.json.

How it works

Every deployment follows the same observable workflow:

inspect project
  -> validate ezdeploy.yaml
  -> preview provider, bindings, access, and risks
  -> obtain explicit user confirmation
  -> bind deployment to the confirmed plan digest
  -> provision or reuse resources
  -> deploy
  -> verify health
  -> persist application state
  -> return URL

Success requires a ready deployment and a verified *.apps.example.com URL when a personal application domain suffix is configured. Provider deployment IDs and fallback hosting URLs alone are not success.

Quick install

One Cloudflare account is the only infrastructure requirement. New accounts must activate R2 once in the Cloudflare dashboard before the first bucket can be created; activation may request a payment method, but usage within the current free allowance is not billed.

npm install
npx wrangler login
npm run setup:cloudflare

The script provisions D1 and R2, writes the Worker configuration, deploys all four Workers, uploads generated secrets, and prints your application-center URL. See docs/cloudflare-setup.md for token permissions, non-interactive flags, and the equivalent manual steps.

Features

The repository includes a deterministic mock for tests and a real Cloudflare adapter:

• manifest validation and safe defaults;
• explicit deployment state transitions;
• resource-binding reuse across repeated deployments;
• health-gated readiness and structured failures;
• persisted control-plane events and structured provider errors;
• explicit deletion with resource retention or removal;
• Pages and Workers deployment with D1/R2 runtime bindings;
• scoped AI virtual keys issued by an OpenAI-compatible proxy and injected as secrets;
• optional Cloudflare Access policies for protected applications;
• immutable Pages artifacts, Worker version capture, and restoration;
• a single-administrator application center plus MCP list, logs, rollback, and delete tools;
• complete English and Simplified Chinese application-center routes with language-preserving navigation;
• ZIP upload for static sites straight from the application center, no agent required.

The mock provider must not be presented as production. A production installation requires a Cloudflare account and deployment of the AI Proxy when AI bindings are used. Cloudflare Zero Trust is optional and only needed for protected application access.

Documentation

Document	What it covers
docs/cloudflare-setup.md	Cloudflare tokens, Worker setup, non-interactive flags
docs/architecture.md	Control plane, providers, and state machine design
docs/ai-provider-management.md	DeepSeek, OpenAI, Anthropic, Gemini, OpenRouter, Workers AI
docs/account-management.md	Single-admin account, sessions, and credential storage
docs/open-source-release.md	Release checklist and repository hardening
CONTRIBUTING.md · SECURITY.md · SUPPORT.md	Community, vulnerability reports, and help

Repository layout

apps/mcp-server       Temporary npx client and optional MCP gateway
apps/control-plane    Authenticated source-upload and deployment API
apps/cloud-control-plane  Online Worker + D1/R2/Workflow control plane
apps/agent-ingress       Public token-authenticated Agent API ingress
apps/ai-proxy         OpenAI-compatible scoped AI gateway
apps/app-center       Authenticated local application catalog
apps/cloud-app-center Online single-administrator application center
packages/contracts    Versioned manifest and domain schemas
packages/core         State machine, SQLite repository, orchestration, providers
skills/ezdeploy      Codex deployment workflow

The production control plane is fully online. A Worker stores applications, environments, deployments, bindings, and events in D1; deployment bundles in R2; and long-running release steps in Cloudflare Workflows. Provider credentials are Worker secrets and never enter an application repository or Agent prompt.

Develop

Requires Node.js 22 or later.

npm install
npm run typecheck
npm test
npm run build

Run the local Mock MCP server for development:

ZAODEPLOY_PROVIDER=mock \
ZAODEPLOY_DATABASE_PATH=.zaodeploy/control-plane.db \
npm --workspace @ezdeploy/agent run dev

The mock provider returns .example.test URLs and must be selected explicitly. Production uses the online @ezdeploy/cloud-control-plane. The default owner flow requires no prior installation or MCP configuration on every project: the application center generates a long-lived, revocable personal deployment key plus an install prompt for the public EZdeploy Skill. After this one-time setup, phrases such as “deploy to my app center” or “部署到应用中心” trigger the workflow. Terminal-capable Agents download a versioned standalone client into an operating-system temporary directory; Remote MCP and an operator-published @ezdeploy/agent package remain optional enhanced distribution paths. No local control-plane daemon or owner-visible Cloudflare Access service credential is required. The old well-known path and ZAODEPLOY_* environment variables are retained as stable legacy protocol identifiers.

AI and organization access are opt-in control-plane capabilities; see .env.example. The AI Proxy keeps the real model-provider key server-side and issues revocable per-application keys. Vite/static applications must call D1, R2, and AI through Pages Functions—never expose ZAO_AI_API_KEY to browser code.

The personal administrator can configure DeepSeek, OpenAI, Anthropic, Gemini, OpenRouter, Cloudflare Workers AI, or a custom OpenAI-compatible endpoint from the application center. See docs/ai-provider-management.md.

See docs/cloudflare-setup.md for Worker and Agent setup. The Gateway builds locally with a minimal environment and uploads a digest-verified bundle containing only the manifest, built assets, compiled Pages Functions, routes, and migrations. Project build scripts never execute in the credential-bearing control plane.

On first visit, the owner creates the installation's only administrator account. EZdeploy stores only a salted PBKDF2 password derivative and hashed, expiring sessions in D1; it never stores the plaintext password or session token. See docs/account-management.md.

Run the application center against the same database:

ZAODEPLOY_DATABASE_PATH=.zaodeploy/control-plane.db \
ZAODEPLOY_APP_CENTER_TOKEN='<personal owner token>' \
npm --workspace @ezdeploy/app-center run dev

When the application center origin is reachable only through Cloudflare Access, use ZAODEPLOY_TRUST_CLOUDFLARE_ACCESS=true instead of local token mode. Do not enable header-trust mode on an origin that can be reached directly.

Product boundary

The first release targets static sites, Vite/React, and Cloudflare Workers. Cloudflare Pages/Workers is the intended runtime; D1, R2, optional protected access, and an OpenAI-compatible AI proxy are resource bindings.

EZdeploy does not aim to become a general container platform, Kubernetes distribution, full CI/CD product, or database implementation.

Open-source status

EZdeploy is being prepared for its first public 0.1.0 release under Apache-2.0. The core deployment workflow is implemented and tested; Cloudflare setup still requires operator-owned infrastructure and security review. The source repository is ezdeployhq/ezdeploy. See CONTRIBUTING.md, SECURITY.md, and the release checklist.

Manifest

Start from ezdeploy.example.yaml. The manifest is the durable source of deployment intent; chat history is not.

License

Apache-2.0.