Build and Run Editable AI-Generated Websites with EmDash Build

What Is EmDash Build?

EmDash Build is an open source AI site builder that turns a written brief into an editable EmDash website. Instead of generating only static page markup, it creates a structured content model, populates that model through EmDash's Model Context Protocol server, and writes typed Astro pages and components to render the content.

The resulting project includes server-rendered pages, structured content, media storage, and the EmDash administration interface. Editors can continue using the site after the initial generation: they can update text and media, add or duplicate sections, reorder content blocks, schedule posts, and ask the agent to make larger content or design changes.

Important: EmDash Build is an alpha reference application intended for hosting providers, website builders, and platforms. Publishing is disabled in the hosted demo.

You can explore the hosted demo, although you cannot publish sites from it.

Key Capabilities

• Structured clarification: The agent asks focused questions when a brief leaves an important decision unresolved.
• Agent-designed content models: It creates collections for reusable entities and structured blocks for page sections that editors can reorder.
• Editable Astro sites: The frontend uses typed Astro components while ordinary content remains manageable through EmDash.
• Live preview and repair: The project is rendered in a private Builder preview. The agent can validate the output, inspect failures, and repair them in the same loop.
• Content workflows: Editors can manage text, media, sections, blocks, and scheduled content through the EmDash admin interface.
• Durable history: Source code and local CMS state are stored as Git commits in Cloudflare Artifacts.
• Controlled publishing: Validated static releases can be packaged for Workers for Platforms, but only when the operator explicitly enables and configures publishing.

How the Architecture Works

Every generated project receives a Cloudflare Sandbox containing a prepared EmDash, Astro, and Tailwind project. A BuilderAgent Durable Object manages the conversation and the model-and-tool loop.

The agent uses EmDash MCP tools to create schemas and content. It writes the public frontend inside the Sandbox, starts a private preview, validates the rendered site, and fixes errors before completing a turn.

Cloudflare Artifacts stores each coherent project state as Git history. If a Sandbox goes to sleep, EmDash Build can restore both the source code and local CMS state into a new container and restart the preview.

The Agent Workflow

1. Understand: Read the brief and identify missing material decisions.
2. Model: Decide which data should become reusable collections and which pages need structured blocks.
3. Build: Create the EmDash schema, refresh generated types, and write typed Astro renderers.
4. Populate: Add representative content and media through EmDash MCP tools.
5. Verify: Type-check the project, render public routes, inspect the preview, and repair failures.
6. Save: Commit the complete project state to Cloudflare Artifacts.

Prerequisites

Local development depends on both local tooling and access to several Cloudflare services. Before continuing, prepare the following:

• Node.js 24 or later
• pnpm 11.9
• A running Docker-compatible daemon
• Wrangler authenticated to a Cloudflare account
• Access to Cloudflare Workers
• Access to Durable Objects
• Access to Cloudflare Sandbox
• Access to Workers AI and AI Gateway
• Access to Cloudflare Artifacts
• Access to Workers for Platforms

Because provider resources and trust boundaries require careful configuration, read the repository's self-hosting guide before deploying the application.

Install and Configure EmDash Build

1. Install Dependencies

From the repository root, install the locked dependency versions:

pnpm install --frozen-lockfile

2. Create the Provider Configuration

Copy provider.config.example.json to the ignored provider.config.json file:

cp provider.config.example.json provider.config.json

Open provider.config.json and replace every example value with the resources for your Cloudflare account. Create the required resources by following the self-hosting guide rather than relying on the example values.

3. Validate and Render the Configuration

Run the preflight checks, then generate the provider-specific Wrangler configuration:

pnpm preflight
pnpm configure

The generated configuration used by the documented local startup command is wrangler.provider.jsonc. Inspect this provider-specific file before deploying or running sensitive environments.

4. Configure Local Secrets

Copy the development secrets template:

cp .dev.vars.example .dev.vars

Add the AI Gateway credentials required by the builder to .dev.vars. An UNSPLASH_ACCESS_KEY is optional; adding it enables stock-image search during generation.

Do not place provider credentials inside generated projects. Publishing is controlled by the server, and generated sites are not given provider credentials.

5. Start the Full Local Application

Start EmDash Build with the generated provider configuration:

EMDASH_WRANGLER_CONFIG=wrangler.provider.jsonc pnpm dev

When the development server is ready, open http://localhost:5173.

6. Start UI-Only Mode When Appropriate

If you only need to work on the interface, use:

pnpm dev:ui

This mode does not start Sandbox-backed site generation. Use the full development command when you need to test the builder agent, project creation, or live generated previews.

Basic Usage: Generate a Site from a Brief

1. Write a Useful Brief

Describe the intended website, its audience, major pages, reusable content, and desired visual direction. For example:

Create a portfolio website for an Icelandic landscape photographer.
Include a home page, reusable photo collections, an about page,
and structured page sections that editors can reorder.

The agent may ask focused clarification questions if the brief leaves important choices unresolved. Answer these questions before expecting a coherent schema and frontend.

2. Let the Agent Model and Build the Site

After clarification, the agent determines which information belongs in reusable collections and which narrative pages should use structured blocks. It then creates the EmDash schema, refreshes generated types, writes Astro renderers, and adds representative content through MCP tools.

3. Review the Private Preview

Use the Builder's live preview to inspect the generated routes and overall design. EmDash Build validates the generated project and can repair detected failures within the agent loop.

4. Continue Editing in EmDash

Once the initial project is usable, manage normal content through the EmDash administration interface. You can edit text and media, add or duplicate sections, reorder blocks, and schedule posts. Return to the agent when you need broader structural, content, or design changes.

5. Save and Restore Project State

Coherent project states are committed to Cloudflare Artifacts as Git history. This persistence allows EmDash Build to restore the project source and local CMS state when a Sandbox has slept and a new container is required.

Validation and Development Commands

Use the repository commands appropriate to the type of change you are making:

• pnpm dev starts EmDash Build with the default configuration.
• pnpm dev:ui starts the interface without Cloudflare Sandbox containers.
• pnpm check type-checks the application and Worker tests.
• pnpm test runs the application test suite.
• pnpm test:worker runs the Workers integration suite.
• pnpm build builds EmDash Build with the default configuration.
• pnpm build:provider builds using wrangler.provider.jsonc.
• pnpm format formats the repository with oxfmt.

Before submitting a contribution, run the complete validation sequence recommended by the project:

pnpm format
pnpm check
pnpm test
pnpm test:worker
pnpm build

Advanced Tips

Choose the Correct Development Mode

Use pnpm dev:ui for isolated interface work because it avoids starting Sandbox containers. Do not use it to verify generation workflows: Sandbox-backed generation is unavailable in UI-only mode.

Separate Content Editing from Structural Changes

Use the EmDash admin interface for ordinary editorial work such as changing text, media, sections, and ordering. Use the agent for larger design or content-model changes. This preserves the project's division between structured CMS data and typed Astro rendering code.

Inspect Provider Configuration

Treat the example provider configuration as a template only. Replace every sample value, run pnpm preflight, generate the Wrangler configuration with pnpm configure, and inspect the output for the target Cloudflare account.

Keep Publishing Explicitly Controlled

Public publishing is server-owned and disabled by default. Only enable and configure it when the operating provider is ready to package validated static releases for Workers for Platforms. The hosted demo also keeps publishing disabled.

Review Security Boundaries Before Deployment

Consult the repository's threat model for details about model tools, Sandbox execution, secrets, private previews, persistence, and publishing. Use the operations guide for operational checks.

Navigate the Repository Efficiently

• src/worker contains Worker routes, the BuilderAgent, prompts, tools, persistence, and publishing controls.
• src/client contains the React Builder interface, chat, activity views, and live preview.
• prototype/builder-cloudflare contains the prepared blank EmDash and Astro scaffold used for new projects.
• migrations contains authentication and provider-control database migrations.
• scripts contains provider configuration, smoke tests, and operational helpers.
• test contains application and Worker coverage.
• docs contains self-hosting, security, operations, and implementation documentation.

Conclusion

EmDash Build combines AI-assisted generation with a durable, editable CMS workflow. It creates structured EmDash content and typed Astro components, validates the result in a private Cloudflare Sandbox preview, and stores project history in Cloudflare Artifacts. Because it is an alpha reference application with significant infrastructure requirements, configure provider resources carefully, review the security documentation, and keep public publishing explicitly controlled.