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

# Apps Overview

> What a DataGen app is, the two app kinds, and how apps connect to agents, context, data and the foundation

An **app** is a web interface your team opens inside DataGen: a dashboard, an
internal tool, a review queue, an analysis notebook. Every app is a folder of
files plus the command that serves it. DataGen runs that command in a sandbox
and shows the result in the workspace, so nobody has to host, deploy or log in
to anything separately.

Apps live under **Apps** in the left navigation (`/signalgen/apps`). The Apps
page groups them by kind.

## How an app runs

* **One shared tree, one instance per member.** The app's files (its published
  version) are shared across the workspace. Each member who opens the app gets
  their own sandbox and their own running process, so one person's session
  never interferes with another's.
* **Opening starts it.** Opening an app checks access, prepares the sandbox,
  loads the published files and waits for the server to answer. A stopped app
  starts again the next time someone opens it.
* **Credentials resolve as the viewer.** When an app is bound to a
  [Connection Vault](/foundation/vault), each member's instance receives that
  member's own credential values as environment variables.

## The two kinds

| | Notebooks | Custom apps |
| - | - | - |
| What it is | A [marimo](https://marimo.io) notebook: reactive Python cells with outputs | Any web service that listens on a port: a Python, Node or static site |
| Where files live | One shared notebooks folder for the whole workspace; each notebook is one `.py` file | The app's own folder |
| How you edit it | Directly in the marimo editor when you open it, or by asking an agent in chat | In the **App Builder**: an AI chat, a live preview and a file editor |
| Versions | The notebook file is edited in place | Save immutable versions, then publish one |
| Created by | **New notebook** on the Notebooks page, or an agent's `create_notebook` tool | **New app** or **Import folder** on the Custom apps page, or an agent's `create_app` tool |

### When to use a notebook

Pick a notebook for exploratory analysis and reports that analysts keep
editing: query a source, chart it, tweak a cell, re-run. Notebooks in the same
workspace share one folder, so one notebook can read files another one wrote.
Each notebook still runs in its own sandbox with its own kernel, so a heavy
notebook never stalls the others.

### When to use a custom app

Pick a custom app when people should *use* the result rather than edit it: a
dashboard with filters, a form-driven internal tool, a portal. Custom apps go
through a save-and-publish cycle, so the version your team sees changes only
when someone publishes.

When you create a custom app you also pick its type:

* **Regular app**: a UI for people, with APIs as needed.
* **MCP app**: a UI for people *and* tools for agents. Agents in the workspace
  can discover and call the app's tools.

## How apps connect to the rest of DataGen

<CardGroup cols={2}>
  <Card title="Agents" icon="robot">
    Agents create, open and call apps with their built-in `apps` tools
    (`list_apps`, `create_app`, `create_notebook`, `open_app`, `request` and
    others). The App Builder chat is itself an agent turn running in the app's
    builder sandbox.
  </Card>

  <Card title="Context" icon="book">
    Connect published knowledge bases to a custom app's builder as read-only
    reference material for the AI writing the app.
  </Card>

  <Card title="Data and Files" icon="database">
    Select workspace files as the app's **Sources**. They are copied into the
    app's `.sources/` folder when it starts. To query a database directly, bind
    a vault credential and connect from code.
  </Card>

  <Card title="Foundation" icon="layer-group">
    Each app pins a **sandbox environment** (the image it boots in), a
    **Connection Vault** (credentials the running app receives) and a
    **harness** (the runtime the builder chat runs on).
  </Card>
</CardGroup>

<Note>
  The harness drives the App Builder's chat only. A running app serves its own
  process and never loads a harness. See [Harness](/foundation/harness).
</Note>

## Lifecycle of a custom app

<Steps>
  <Step title="Build">
    Describe the app in the App Builder chat. The AI edits a **draft** in the
    builder sandbox while you watch the live preview.
  </Step>

  <Step title="Save a version">
    **Save** snapshots the draft as an immutable version and installs its
    dependencies into an image for that version.
  </Step>

  <Step title="Publish">
    **Publish** a saved version from **Versions**. That version is what every
    member gets when they open the app. Publishing an older version rolls back.
  </Step>

  <Step title="Use and automate">
    Members open the app at `/signalgen/apps/<appId>/view`. Automations can run
    the builder on a schedule to refresh the draft.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="Build an app" icon="hammer" href="/apps/build">
    Create a notebook or a custom app and configure how it runs.
  </Card>

  <Card title="Publish and share" icon="share-nodes" href="/apps/publish-and-share">
    Save and publish versions, control access and schedule automations.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.