> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsby-1791319236-3be7a15.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Apps

> Build custom UIs that run inside LangSmith and call the LangSmith API, either by chatting with LangSmith Chat or locally with the LangSmith CLI.

<Note>
  Custom apps are available on [**Plus** and **Enterprise** plans](https://www.langchain.com/pricing).
</Note>

A custom app is a UI you build that runs inside LangSmith and calls the [LangSmith API](/langsmith/smith-api-ref). Use one for a workflow the built-in UI does not cover, such as a purpose-built annotation surface, an experiment comparison view, or a dashboard scoped to your own traces.

Deployed apps appear under **Custom Apps** in the sidebar for everyone in the workspace with the `custom-apps:read` permission. You do not host a separate service or manage a separate login.

An app runs in a sandbox with no network access of its own. The host forwards its LangSmith API requests with the viewer's credentials, so each person sees only the data their [permissions](/langsmith/organization-workspace-operations) allow. The host forwards nothing else, and it blocks the endpoints for API keys, members, users, identities, roles, permissions, SCIM, and service accounts.

## Build an app

Build an app by [chatting with LangSmith Chat](#build-with-chat) in the browser, or [locally with the CLI](#build-locally-with-the-cli) and your own coding agent. Both paths produce the same app and store the same source, so either one can [edit](#edit-an-app) what the other built.

### Build with chat

Building in the browser has two requirements:

* **Sandboxes**: Each session runs in a [sandbox](/langsmith/sandboxes). On self-hosted deployments, [enable sandboxes](/langsmith/deploy-self-hosted-full-platform#enable-sandboxes) first.
* **Permissions**: The `custom-apps:create`, `custom-apps:update`, `custom-apps:delete`, and `custom-apps:download` permissions, plus the [sandbox permissions](#permissions).

Without both, the **App** action opens the CLI instructions instead. Chat also needs a [model API key set for the workspace](/langsmith/chat#get-started) before it can send a message.

To build an app with chat:

<Steps>
  <Step title="Start a new app">
    Go to **Custom Apps** and select **App** to open chat. In a workspace with no apps yet, the page opens chat directly.
  </Step>

  <Step title="Describe what you want to build">
    Type what the app should do into the composer, and select the model to build with from the model menu in the composer. The composer accepts a prompt while the sandbox behind it is still starting. When Chat starts writing files, LangSmith saves a draft and opens the **Preview** and **Code** tabs beside the chat.
  </Step>

  <Step title="Review what Chat built">
    The **Preview** tab renders a live build of your changes. The **Code** tab holds the file tree, the source, and the changes from the session. A badge in the header counts the changed files.
  </Step>

  <Step title="Deploy the app">
    Select **Deploy**. The first deploy asks for a name, builds the app, and publishes it to the workspace.

    If you leave the page before the first deploy, LangSmith discards the app. Once Chat has started editing, LangSmith asks before discarding it.
  </Step>
</Steps>

### Build locally with the CLI

Building locally uses the [LangSmith CLI](/langsmith/langsmith-cli), which scaffolds a starter, runs it in a real sandbox on your machine, and uploads it when you are ready. To build an app locally:

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    curl -fsSL https://cli.langsmith.com/install.sh | sh
    ```

    For Windows, Homebrew, and other options, see [Install](/langsmith/langsmith-cli#install).
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    langsmith auth login
    ```

    To use an API key instead, set `LANGSMITH_API_KEY`, plus `LANGSMITH_ENDPOINT` for a self-hosted instance. For profiles and other options, see [Authenticate](/langsmith/langsmith-cli#authenticate).
  </Step>

  <Step title="Scaffold an app">
    ```bash theme={null}
    langsmith apps init --name my-annotation-view --template annotation-queue
    ```

    `init` creates a directory named after the app and, if `npm` is on your `PATH`, installs its dependencies. It also writes an `AGENTS.md` that gives a coding agent the conventions and API surface it needs to produce a working app on the first pass. Omit `--template` for a blank single-file starter.
  </Step>

  <Step title="Iterate locally">
    ```bash theme={null}
    cd my-annotation-view
    langsmith apps dev
    ```

    The app runs in the same kind of sandbox it gets inside LangSmith, with API calls proxied through your own credentials. Failed calls and uncaught errors stream to the terminal, so most debugging needs no browser devtools. Add `--verbose` for every successful call and all console output, or `--quiet` to silence the app.
  </Step>

  <Step title="Push it live">
    ```bash theme={null}
    langsmith apps push
    ```

    The first push creates the app and records its ID in `.langsmith/app.json`, which links the directory to it. Later pushes update the same app. Commit that file so teammates push to the same app.
  </Step>
</Steps>

#### Starter templates

Pass one of these to `langsmith apps init --template`:

| Template | What it scaffolds |
| - | - |
| `annotation-queue` | A queue-review UI: run and thread items, a type-specific viewer, and a feedback rubric. |
| `annotation-queue-grid` | The same review workflow as an editable spreadsheet. |
| `experiment-comparison` | A side-by-side comparison of evaluation experiments against a baseline. |
| `coding-agent-dashboard` | Charts over coding-agent runs: usage, cost, errors, and activity over time. |

## Edit an app

Edit an app in the browser with chat, or pull its source and edit it locally.

### Edit with chat

Open an app from **Custom Apps** and select **Edit**. The published app is replaced by the editing workspace: chat on the left, and the same **Preview** and **Code** tabs on the right.

Ask for the change in chat, or edit a file directly in **Code** and save it with `Cmd+S` (`Ctrl+S` on Windows and Linux). Either way, the preview rebuilds, and the badge in the header updates its count of changed files.

Two actions end the session:

* **Deploy**: Builds the app and publishes it as a new version for the workspace.
* **Cancel**: Leaves without deploying. Undeployed changes stay in the editing sandbox.

Editing runs in a sandbox that stops after a period of inactivity. Reopening the app wakes the sandbox with undeployed changes intact. If the sandbox has been deleted, select **Recreate from saved source** to rebuild the session from the last deployed source. Undeployed changes are lost.

To rename an app, copy its ID, or change who it is shared with, select **Edit** from the row menu in the app list.

### Edit locally with the CLI

A deploy from the browser stores the app's source, and so does `langsmith apps push`. To edit an app locally, pull it down:

```bash theme={null}
langsmith apps pull my-app
npm install --prefix my-app
```

Edit the source with your own coding agent, then run `langsmith apps push` to publish it.

The scaffolded `AGENTS.md` asks the agent to keep a `context.md` at the app root as the app's memory: what the app does, which files matter, and the decisions behind them. Any root file travels with the source, so a teammate who pulls the app starts from what you learned rather than from scratch.

## Share an app with your organization

A custom app belongs to the workspace it was created in. To share one with the organization, open the row menu in the app list, select **Edit**, then select **Share with organization**. Every workspace in the organization can then see, update, and delete it.

To move a shared app back into a single workspace, select **Pull into this workspace** from that workspace. If the workspace already has an app with the same name, LangSmith asks you to rename it.

When the CLI resolves an app by name, a workspace app wins over an organization app of the same name.

## CLI reference

| Command | What it does |
| - | - |
| `langsmith apps init --name NAME [--template TEMPLATE]` | Scaffold a starter app in a new directory named after the app, and install its dependencies. |
| `langsmith apps dev` | Run the current directory's app locally in a real sandbox. |
| `langsmith apps push` | Upload the current directory as a custom app, creating it on the first push. Pass `--no-build` to upload the current files as-is. |
| `langsmith apps pull APP_ID_OR_NAME` | Download an app's source into a new directory. |
| `langsmith apps list` | List custom apps. |
| `langsmith apps delete APP_ID_OR_NAME` | Delete an app by ID or name. Pass `--yes` to skip the confirmation. |

`dev` and `push` act on the current directory, so change into the app's directory first.

## Permissions

The `custom-apps:*` permissions control access to custom apps. For the full table, see [Custom apps](/langsmith/organization-workspace-operations#custom-apps).

Editing in the browser also requires the `sandboxes:create`, `sandboxes:read`, `sandboxes:update`, `sandboxes:delete`, and `sandboxes:exec` permissions, because each session runs in a sandbox. The **Edit** action appears only for users with `custom-apps:update`, `custom-apps:download`, and the sandbox permissions.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/custom-apps.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>