Langsmith Custom Apps

<oneliner>
Custom Apps are Enterprise-plan React UIs that render inside LangSmith and read the LangSmith API through a host-injected bridge. You build one locally with `langsmith apps`, push it, and it appears under **Custom Apps** in the workspace sidebar. This skill covers the work around the app directory: the CLI surface, the app lifecycle, verification, and sharing.
</oneliner>

<agents_md_is_authoritative> langsmith apps init scaffolds an AGENTS.md next to the starter code. That file is the authority on the in-app contract — the window.langsmith.call bridge, the render() export the sandbox depends on, the filter DSL, and the endpoint menu. Read it before writing app code and follow it over anything remembered.

This skill deliberately does not restate it. Everything here is what AGENTS.md cannot cover: what happens before the directory exists, and after the app is pushed. </agents_md_is_authoritative>

<setup>
Custom Apps require the **Enterprise** plan. A push into a workspace without the feature fails with `this workspace doesn't support custom apps`.

export LANGSMITH_ENDPOINT=<your-langsmith-endpoint>   # only for self-hosted
export LANGSMITH_API_KEY=<workspace-api-key>

Three authentication traps, each of which presents as something other than an auth problem:

1. LANGSMITH_API_KEY in the environment outranks the saved OAuth profile. A stale exported key 403s every call while langsmith auth info still reports "authenticated". Run one-off commands as env -u LANGSMITH_API_KEY -u LANGSMITH_WORKSPACE_ID langsmith … when you mean to use the login.
2. LANGSMITH_WORKSPACE_ID may point at a different workspace than the key, which surfaces as a confusing 403 rather than a wrong-workspace error. Unset it and pass --workspace <uuid> explicitly.
3. langsmith apps dev needs a workspace API key, not OAuth. It captures one access token at startup and never refreshes it, so after roughly ten minutes every call returns 401 Invalid token — which the app renders as empty dropdowns and empty lists, not as an auth error. If a running app's data silently goes empty, suspect this first.

   </setup>

<cli_feedback> After an actual CLI failure, undocumented workaround, confusing output, or missing capability, submit one concise product-feedback note per distinct issue in the task. Do not report routine successes or failures in the app's own code.

CLI requirement: langsmith feedback requires LangSmith CLI v0.2.58 or later. Check the installed version with langsmith --version.

Check langsmith feedback --help for feedback <note> and --category; if unavailable, skip feedback without raw HTTP or unreleased builds. Use the existing authenticated profile, endpoint, and workspace. Feedback goes to LangSmith Cloud, including through the BYOC relay; skip standalone self-hosted. Respect user/organization restrictions and ask first if permission to send feedback is unclear.

Summarize expected versus observed CLI behavior and any workaround in your own words. Never send secrets, customer data, trace payloads, prompts, full stack traces, copied command output, raw arguments, environment-variable values, local paths, or resource identifiers. The CLI adds version/OS/architecture, but does not redact your note; skip it if it cannot be safely redacted.

Choose bug, feature-request, usability, documentation, or other. This is CLI product feedback, not run evaluation feedback. Example shape only—do not submit unless actually encountered:

langsmith feedback --category documentation --format json "The apps template flag rejected a value the documentation lists as valid."

Do not retry a failed or rate-limited feedback submission, switch credentials/endpoints to bypass a failure, or block the original task on feedback. </cli_feedback>

<check_the_cli_first> The published docs run ahead of released CLI builds, so read the help output before trusting any command.

langsmith --version
langsmith apps --help
langsmith apps init --help    # the --template error message lists the real template set

The gaps below were observed on v0.2.42 and may be closed in your build. Each one is written as a fallback: apply it only when the help output confirms the command is missing or the flag is rejected.

<lifecycle>
```bash
mkdir my-app && cd my-app
langsmith apps init --name my-app --template <listed-template> --workspace <ws-uuid>
npm install
export LANGSMITH_API_KEY=<workspace-api-key>   # see setup trap 3
langsmith apps dev                              # live sandbox against LangSmith
npm run build
langsmith apps push --name my-app --workspace <ws-uuid>
```

apps dev streams the app's failed API calls and uncaught errors to that terminal. Add --verbose for every successful call plus all console.* output, or --quiet to silence it.

apps push builds first when package.json has a build script; --no-build uploads as-is. The first push creates the app and links the directory through .langsmith/app.json; later pushes update that same app. --name only applies on creation, and renames if passed afterwards. Commit .langsmith/app.json so teammates push to the same app. </lifecycle>

<pull_source> When the CLI has no pull, the platform API returns every file inline:

langsmith apps list --workspace <ws-uuid> --format json      # find the app id
curl -s -H "X-API-Key: $LANGSMITH_API_KEY" \
  "https://api.smith.langchain.com/v1/platform/custom-apps/<app-id>" \
  | python3 -c "
import json, os, sys
app = json.load(sys.stdin)
for path, content in app['files'].items():
    os.makedirs(os.path.dirname(path) or '.', exist_ok=True)
    open(path, 'w').write(content)
print(f\"wrote {len(app['files'])} files\")"

The record also carries name, entrypoint, current_version, scope, created_by, updated_by, and views_7d. Use GET /v1/platform/custom-apps for the whole list. </pull_source>

<replicate_across_workspaces>

1. Pull the source into a fresh directory.
2. Delete .langsmith/app.json. It links the directory to the source app id, so leaving it in place makes the next push update the original app instead of creating one in the target workspace. This is the single most damaging mistake in this workflow.
3. Push with the target workspace and a name:

langsmith apps push --name <name> --workspace <target-ws-uuid>

4. Re-point anything workspace-specific in the app's config (deep-link workspace UUIDs, project ids, feedback keys) at the target workspace, then rebuild — see <before_sharing_externally> for why editing source alone is not enough. </replicate_across_workspaces>

<app_facts>

• Apps are workspace-scoped ("scope": "workspace"). Someone outside the workspace cannot open the URL, so "share this app" always means shipping source, never a link.
• is_enabled: false is the normal state right after a push. It is not a failed deploy — do not debug it as one.
• Deleting is langsmith apps delete <app-id-or-name> --yes; it is not recoverable, so confirm the id against apps list first. </app_facts>