What you do from your MCP client, and what aeria does for each call. A session is a branch is a sandbox: the unit of work, with its own sandbox, its own preview, its own events.

1 create   app_create                    the seed forked, production running
2 branch   app_branch_create             a branch from main: a session
3 change   app_file_*, app_command_run   in the branch's sandbox
4 preview  app_preview                   the branch built, on its own host
5 promote  app_promote                   merged, production updated

Every call is an event of its app and branch, pushed to the web app as it happens.

1. Create an app

app_create {name} makes an app from the seed: its repository forked in Cloudflare Artifacts, its own D1 database and R2 bucket made, the seed’s kept build uploaded as its production. Nothing is built: it answers {app, url} at once, production running at <app>-<workspace>.aeria.run.

To find an app: app_search, then app_show (its host, its open branches, previews and deployments).

2. Start a branch

app_branch_create {app, name} cuts a branch from main: a session. Its sandbox starts at its first exec.

• Its name: lower-case letters, digits and single dashes, starting with a letter; never main. Its preview’s host <app>-<branch>-<workspace> is 63 characters at most, refused taken when another host has it.
• The same name again joins that open branch: the answer warns that another session wrote it (when, its last commit).
• Every other code tool names an open branch of that app, else it is refused no_branch.

3. Change its files

• app_file_read, app_code_search: read from Cloudflare Artifacts, no sandbox.
• app_file_write, app_file_delete, app_file_move: an exec in the branch’s sandbox: checkout, change, commit, push. It answers {branch, commit, steps}.
• app_command_run {app, branch, command}: any command in the checkout (bun add zod, a script), its output answered, its changes committed and pushed.
• app_test, app_check: the tests, the lint and types.
• The generators (app_model_create, app_page_create…): each runs one of the seed’s own commands (Tools).

Your client never runs git and never holds a credential. One exec runs at a time per branch: another call meanwhile is refused busy, naming the exec that holds it.

A sandbox stops after a short idle time, its whole disk kept in a snapshot first; its next start restores it in about 1.5 s. When the snapshot is gone (30 days, or a new sandbox image), the start is cold: the checkout cloned again, the answer says so (cold: true, why).

4. Preview the change

app_preview {app, branch} runs [checkout, install, test, build] in the branch’s sandbox, keeps the bundle, and deploys it on the branch’s own host, <app>-<branch>-<workspace>.aeria.run. It answers {url, steps}.

• Production is untouched: the preview has its own script, its own D1 and R2, and its settings’ preview values. It never opens a connection.
• Its database: main’s migrations, then the branch’s. fresh_database: true makes it again from them (after a migration was renamed or removed).
• A build depends on its source tree only: the same tree reuses the kept bundle (build: "reused").
• A failed step answers with every step’s output; nothing is uploaded.

5. Promote it

app_promote {app, branch} is at ask: it waits for your answer. Once allowed, it promotes exactly the bundle its preview showed:

1. production’s D1 bookmarked (Time Travel), then the branch’s migrations run;
2. the bundle uploaded as production;
3. main moved to the branch, fast-forward;
4. the branch closed and purged: its preview, its D1 and R2, its sandbox and snapshots. Its code lives on in main; its events are kept.

It answers {url, deployment}. An upload that fails stops the promote there, with why: production runs its last deployment, main has not moved, the branch stays open to promote again.

When a promote is refused

Refusal	Why	What your agent does
behind_main	main moved since the branch was cut	app_branch_rebase, app_preview, then promote again
preview_stale	commits after the branch’s last preview	app_preview, then promote again
conflict	the rebase met a real conflict, its files named	fix the files, rebase again
migration_clash	two migrations with the same number	rename one (app_file_move), rebase again

A migration only adds: it never drops nor renames a table or a column (the build refuses it), so an earlier deployment still runs on the new schema.

After

• Roll back: app_rollback uploads an earlier kept bundle. Production runs main, but after a rollback, which serves the earlier deployment until the next promote.
• Restore data: app_database_restore puts production’s D1 back to a point in time, within its last 30 days.
• Close a branch unpromoted: app_branch_close purges it as a promote does; its commits stay in the repository, its events are kept.
• Archive an app: app_archive hides it, stops its schedules, and closes its open branches; its host stops serving. Its repository, database, bucket and bundles are kept: nothing a person owns is deleted.