Sandboxes
A sandbox is the agent’s session, much 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_sandboxis 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 a few minutes; the next call wakes them again.
- Uncommitted files don’t survive a sandbox reset, so commit at working checkpoints, not only at the end.
create_sandbox also returns a framework guide: the concise spec of how Zite apps are structured. See
The framework guide.
The loop
1
Create the app
create_app scaffolds an empty app at apps/<dir>/. This is a free scaffold, so no AI build runs.2
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.3
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.4
Check
check_app refreshes .zite/db.ts from the live database, regenerates types, and type-checks every
app. Fix everything it reports before committing, because commit doesn’t type-check.5
Commit
commit commits and pushes, and kicks off a background build and snapshot of the apps it touched. It
returns the editor URL to share. Builds run in the background, so a fresh commit reports
buildStatus: "building". To rebuild code that reached main another way, use build_app.6
Verify at runtime
A clean type-check doesn’t prove the app works. SQL identifier mistakes and integration errors only
surface at runtime. Try key queries and integration calls with
run_one_off_script, which runs in the
same runtime as workflows. It writes to the live database, so ask before seeding data or remove what
you add. Then pull get_logs to check the workflows’ runs for errors.7
Publish
publish_app takes the latest successful build live. External apps get a zite.so URL. See
Publishing.Data access
The frontend never touches the database directly. It calls backend workflows, which query the 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, because findAll
returns 500 records unless you pass a limit, and 2,000 at most.
Conventions
- Project layout: imports via
zitejs/*and@project/components/ui/*aliases; never edit generated.zite/orsrc/main.tsx; install any other npm package into the app withnpm install <pkg> -w apps/<dir>viabash. - Build tools: every tool’s parameters and behavior.