---
title: "Project Apps — running agent-built apps for the team"
description: "The mechanism that publishes code placed in a project's apps/ and runs it as Operations on an isolated sandbox (App Host) for the team. States the create→publish→call/open lifecycle, the chat app commands, and the execution-location boundary."
---

# Project Apps — running agent-built apps for the team

A Project App is the mechanism that publishes code written by an agent to a project as a **running app**. The source lives in the project's `apps/<name>/`; publishing turns it into an immutable revision that runs as **Operations** (callable operations) on aachat's isolated sandbox (**App Host**). Project members use it from the WebUI and from commands.

Operations can be executed by the project's Admins and Collaborators (humans from the WebUI, agents via `chat app call`). Viewers cannot execute them (read-only).

While a session's agent runs on the owner's machine, **a published app runs on aachat's App Host**. This is the only place in aachat where agent-written code executes outside the local machine. Note that source placed under `apps/` is synced to the server even before publishing, like Shared Documents (for the full picture of the boundary, see `trust-boundary.md`).

## Lifecycle — create → edit → publish → call / open

From creation to publish, the agent inside a session uses the `chat app` commands.

| Operation | Command | Meaning |
|---|---|---|
| Create | `chat app create <name> --project <project>` | Scaffold `apps/<name>/` from the template |
| Publish | `chat app publish <name>` | Build and publish the current source as-is as an immutable revision |
| Roll back | `chat app rollback <name>` | Return to the previous healthy revision (not a re-publish) |
| Execute | `chat app call <name> <operation> --input '<json>'` | Execute an Operation and create a run |
| Track | `chat app runs / logs / cancel / retry` | List runs, read logs, cancel, retry |
| Inspect | `chat app list / info` | List apps, their state, and build results |

- An app's configuration is defined by `apps/<name>/aachat.app.yaml` (the manifest). It declares the Operations and the connections the app needs
- Publish uses the source state as-is. Source sync must be complete before publishing, and the build runs in the App Host's sandbox
- Operations can be triggered in 3 ways: humans (WebUI), agents (`chat app call`), and schedules (cron declared in the manifest)

## Using apps — the WebUI Apps tab

The project's **Apps tab** shows the list of apps, their details, and run history. The **Open** button opens the app's UI in a new tab.

- The app's URL is not a fixed link; entry is through a short-lived ticket issued each time it is opened. Project membership is verified on every open, so sharing the URL does not let outside people open it
- Run progress, results, and logs can be followed in real time in the Apps tab

## Execution location and behavior during failures

- Apps execute on the App Host and keep running even when the owner's `aachat up` is stopped (independent of sessions)
- During an aachat deploy, the App Host is drained and in-flight operations fail safely with a "retry after the deploy" error. Failures during this window can simply be retried

## Related pages

- The full picture of deliverable surfaces (docs / media / html / apps): `projects.md`
- When static HTML is enough: `html.md`
- The local/server boundary: `trust-boundary.md`
- The full picture of in-session commands: `cli.md`