> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The build loop

> How an agent goes from an empty sandbox to a published app: sandboxes, editing, checking, committing, and verifying.

Building a Zite app with the MCP follows a tight loop that mirrors how Claude Code works: boot a sandbox,
write code, check it, commit, and publish — verifying at runtime before calling it done.

## Sandboxes

A sandbox is the agent's session — think of it like a browser tab. `create_sandbox(workspaceId)` boots a
cloud environment with the workspace's whole monorepo checked out, and returns a `sandboxId` plus the file
tree and the apps already in the workspace.

* **Every build tool takes the `sandboxId`** — `create_sandbox` is the only tool that returns one.
* **One sandbox per chat.** Two chats get separate sandboxes, so they never clobber each other.
* **You can work on any app in the workspace** from one sandbox, and creating a new app stays in the same session.
* Idle sandboxes stop automatically after about 15 minutes; the next call transparently re-boots.

`create_sandbox` also returns a **framework guide** — the concise spec of how Zite apps are structured. See
[The framework guide](/ai-skill).

## The loop

<Steps>
  <Step title="Create the app">
    `create_app` scaffolds an empty app at `apps/<dir>/`. This is a free scaffold — no AI build runs.
  </Step>

  <Step title="Write workflows and UI">
    Add backend workflows in `src/api/` and the React frontend in `src/`. Use `edit_file` for changes
    (exact string replacement) and `write_file` for new files. Use `grep` and `read_file` to navigate.
  </Step>

  <Step title="Regenerate types">
    After adding, renaming, or deleting workflow files, run `npx zitejs generate` from the workspace root
    via `bash` — it refreshes the typed `zitejs/api` client. `check_app` and `commit` also run it for you.
  </Step>

  <Step title="Check">
    `check_app` runs the type-check and build validations. Fix everything it reports before committing.
  </Step>

  <Step title="Commit">
    `commit` type-checks, commits and pushes, and kicks off a background build and snapshot. It returns the
    editor URL to share. Builds run in the background, so a fresh commit reports `buildStatus: "building"`.
  </Step>

  <Step title="Verify at runtime">
    A clean type-check doesn't prove the app works — SQL identifier mistakes and integration errors only
    surface at runtime. Exercise the key workflows (seed a record, call the dashboard workflow) and pull
    `get_logs` to check for errors.
  </Step>

  <Step title="Publish">
    `publish_app` takes the latest successful build live. External apps get a `zite.so` URL. See
    [Publishing](/deploy/publishing).
  </Step>
</Steps>

## Data access

The frontend never touches the database directly — it calls backend [workflows](/framework/workflows), which
query the [database client](/framework/database-client) (`zite.<Table>` and `zite.sql()`). Read `.zite/db.ts`
first for exact table and field names, and prefer `zite.sql()` for counts, joins, and aggregates — `findAll`
caps at 2,000 records.

## Conventions

* **[Project layout](/framework/project-structure)** — imports via `zitejs/*` and `@project/components/ui/*`
  aliases; never edit generated `.zite/` or `src/main.tsx`; only the bundled frontend libraries compile.
* **[Build tools](/mcp/build-tools)** — every tool's parameters and behavior.