> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# App Builder

The App Builder is the workspace in the RocketRide VS Code extension that
takes an app from an empty folder to a version your team can open. It owns
the work that sits between an app that runs on your machine and one your
team can use: scaffolding the project, previewing it against a real engine
while you edit, packaging it, and deploying versions you can publish, all
without leaving the editor. If you are not yet sure what an app is or
whether you need one, read [Apps](/concepts/apps) first. Switch the
RocketRide sidebar to apps mode and pick an app, or open its `<name>.rrapp`
file, and the builder opens on it.

Where a step has a command-line equivalent, it is shown after the step, so
the same loop runs from a terminal or CI.

## Before you start

- The extension, installed and signed in
  ([installation](/clients/vscode/installation)).
- Node and **pnpm**. Use pnpm, not npm: running `npm install` inside an app
  folder can corrupt the workspace layout. Dependencies install once at the
  workspace root.
- A developer id for your organization, on RocketRide Cloud. Every app id
  is `<developerId>.<name>`. Your organization claims its developer id
  once, in the New App wizard in VS Code, on the Deploy tab, or with the
  npm CLI's
  `rocketride app developer register <id>`, which talks to the deployment
  target named by `ROCKETRIDE_DEPLOY_URI` and `ROCKETRIDE_DEPLOY_APIKEY`
  (the pip CLI has no `app developer` verbs). The id is lowercase letters
  and underscores, starting with a letter; `local`, the prefix of an app
  scaffolded before registering, is reserved, so pick another id.
  Registering is an org admin's step, and permanent. The organization can
  then deploy only apps inside that namespace. A self-hosted server
  registers nothing: it publishes under the fixed id `rocketride`. Until
  the prefix of your app's id matches, the Deploy tab is read-only with a
  banner. An app still on `local.<name>` can move into your namespace from
  that banner in VS Code (see [Create](#create-dashboard-tab)); rename any
  other id by hand. Design and Package always work.
- Catalog nodes only, if the app is headed for the store. Pipelines in a
  store app use the nodes that ship with the engine and nothing else; see
  [Adding a pipeline to your app](#adding-a-pipeline-to-your-app).

## The loop

The builder's tabs, in the order you meet them the first time. After
that, you come back to Design and Deploy most often.

### Create (Dashboard tab)

Start from the Dashboard tab, or run **RocketRide: New App** from the
command palette. The wizard asks for a name and a template (Blank or
Dashboard) and scaffolds the app under `apps/<slug>-ui`. Always create apps
this way; a hand-made folder fails later with symptoms far from the cause.
If your organization has no developer id yet, the wizard's Developer ID
field lets you claim one before you create the app. Skip it and the
scaffold starts the id at `local.<slug>`; renaming the id later makes it a
different app, though an app still on `local.<name>` can move into your
namespace from the Deploy tab's banner in VS Code.

The `<name>.rrapp` file it creates holds only the app id. Opening it opens
the App Builder; the app's identity lives in `package.json`.

What you will edit:

| File | What it is |
| --- | --- |
| `package.json` | the app manifest (`appManifest`): id, name, icon, README, included folders |
| `README.md` | your listing text |
| `icon.svg` | your listing icon |
| `src/App.tsx` | the screens |
| `src/AppDescriptor.ts` | how the app presents itself to the shell |

```bash
rocketride app create reports --template Dashboard
```

Both the wizard and the command create the app in `apps/reports-ui` and take
the developer id from your account. The command reads the account from the
credentials in `.env`, so run `rocketride login` (or `rocketride init`)
first. Without an account it warns and uses `local`; pass
`--developer <id>` to choose one yourself.

An app created as `local.<slug>` can move into your organization's
namespace once the organization has a developer id: in VS Code, the
read-only banner on the Store and Deploy tabs offers **Move to
`<developerId>.<slug>`**. After you confirm, it rewrites the id in
`package.json` (plus the publisher and package name, if they still hold
the scaffold's values), and in the `.rrapp` file and
`src/AppDescriptor.ts` where they carry it, then reopens the App Builder
on the new id. Nothing on the server is renamed: the app's saved settings in
the App Builder and the preview start fresh. Only `local.` ids move this
way; rename any other id by hand in the same files.

### Design

The Preview pane is the real shell, running against your connected engine,
with your app loaded inside it. Every save rebuilds and reloads. The
bundle you are previewing is a personal overlay that only you can see, and
it disappears when the panel closes or the connection drops, so
development work never reaches other users. **Components** is a live
gallery of everything importable from `shell`, and **Console** shows your
app's own console output as it runs.

Your app's state does not disappear with the bundle: what the preview saves
(`prefs`, `appState`) lives in the signed-in user's file store on the
connected engine (with **Inherit Auth** on, the preview is signed in as you
are), in a file named after the app id, and survives closing the panel.
A copy of the app opened on another server, or a working copy under a
different app id than the published app, has its own state, so edits in
one do not show in the other. Deploying a new version keeps the state. On
the same server, user and app id the two read one file but nothing syncs:
the last save wins, so finish in one, close it, then reload the other
before editing there. Files your app writes itself through the shell
connection are stored per server and user only, so a development build
and the published version on the same server share them.

:::note If the preview keeps showing a sign-in screen
With **Inherit Auth** off, an app that requires sign-in boots signed out on
purpose; turn it on to reuse your session. If it still bounces, the host
session is stale: sign out of VS Code and back in, then reload the preview.
:::

### Package

The Package tab edits the `appManifest` block in `package.json`. The file
is the truth, so editing it by hand is fine. Verification needs no server:

```bash
rocketride app verify ./apps/reports-ui
```

### Your listing

Your listing is `README.md` and `icon.svg`, declared in `appManifest`
(`readme` and `icon`) and editable on the Package tab or by hand. Both
files must live inside the app folder. Versions are immutable, so replace
the scaffold README before your first deploy.

### Deploy

Two verbs, and they are not the same:

- **Deploy** uploads your app's source; the server builds it into the next
  immutable version. Deploying activates nothing.
- **Publish** points an audience at a version: `@me` for your own desktop,
  `@team/<name>` for a team. First release, update, and rollback are all
  the same move: repoint, never rebuild. There is no org-wide rung; an
  org-wide audience is a team your admin maintains.

A deploy returns as soon as the server accepts the upload; the version
can be published, and served, only once its server build finishes. The
version card shows the build's progress (`queued`, `building`, …) until
then. If the build fails, the Dashboard says so, and its **View build log**
button opens the server's build log with the reason at the end. From the
terminal, run `rocketride deploy log <appId> <version>`. Once you publish,
**Where this app is live** on the Deploy tab shows
what a browser in each audience actually gets: `serving`, or why not
(`not serving: still building`, `not serving: build failed`, `disabled`,
`in review`). The dashboard says which version you would get right now.
Every open App Builder updates when a build lands or anyone in your
organization publishes or disables a version.

A deploy packs the app folder plus any folders listed under
`appManifest.include`, and nothing else. Every `include` entry must exist.

```bash
rocketride app deploy ./apps/reports-ui --comment "first version"
```

To preview from the terminal instead of the App Builder, run `rocketride app
dev reports --open`: it serves the app, opens the preview, and updates it on
every save, whichever editor you use. Ctrl+C stops it.

Publishing happens on the Deploy tab, or from the terminal:

```bash
rocketride app deploy reports --publish @me   # deploy, wait for the build, publish to your desktop
rocketride app publish reports 2 --to @team/QA
rocketride app versions reports                # the version rail
rocketride app where reports                   # which audiences serve which version
```

The deploy and publish commands need a deployment target
(`ROCKETRIDE_DEPLOY_URI` and `ROCKETRIDE_DEPLOY_APIKEY`, written by
`rocketride login`) and refuse to run without one; `app create` uses the
development connection (`ROCKETRIDE_URI`) to vendor platform packages, and
`app verify` needs no connection.

## Adding a pipeline to your app

There are two ways, and they are different features. See
[Apps and pipelines](/concepts/apps#apps-and-pipelines) for the idea; this
is the how-to.

Either way, a pipeline in an app you intend to publish to the store may use
catalog nodes only: the nodes that ship with the engine, listed in the
[node catalog](/nodes). A custom node exists only on the engine that loads
it; RocketRide Cloud loads none, and a few catalog nodes are marked
unavailable there. Store reviewers reject a pipeline that references
anything else, and no preflight warns you first. If a step has no catalog
node, keep that logic in the app, or give an agent step bounded Python
through the `tool_python` node; ask for a catalog node only for a step
that must run inside the engine, rather than building one for the app.

### Inside the app: runs per user, on demand

Put the `.pipe` file in the app folder and import it. The scaffold's build
treats `.pipe` as JSON. Start it from the shell connection:

```typescript
import summarizer from './summarizer.pipe';
import { useShellConnection } from 'shell';

const { client } = useShellConnection();
const { token } = await client.use({ pipeline: summarizer, useExisting: true });
```

Every signed-in user gets their own instance. Start it once per session and
keep the token; `useExisting: true` re-attaches after a reload instead of
failing because the pipeline is already running. To run two instances for the
same user at once, give each `use()` its own unguessable `token` (keep the
`tk_` prefix). The instance stops by itself after about `ttl` seconds with
no pipeline data request and no pipeline activity event (`apaevt_*`).
The default is 15 minutes; `ttl: 0` disables the timeout. Status polling
and raw stdout/debugger events do not reset the timer. The check runs once
a minute, so the stop can come up to a minute early. The pipeline ships
with the app on deploy. Use this for work that happens when the user
asks for it; it is the default, and the right choice unless the pipeline is
a service shared by a whole team.

### Outside the app: shared, on a schedule

Build the pipeline as its own project and deploy it separately:

```bash
rocketride deploy add pipelines/nightly-report.pipe --comment "v1"
rocketride deploy publish <projectId> 1 --team <teamId>
```

The app does not start this pipeline. It imports the `.pipe` for its
identity only and asks the shell client for the running task's token
(`getTaskToken`) to attach to the instance the team is running:

```typescript
import nightly from '../../../pipelines/nightly-report.pipe'; // identity only
const projectId = String(nightly.project_id);
```

When no run is active, there is no token. That is a normal state, not an
error; show the feature as offline and check again later. A cron start and
`ttl` do not define fixed opening hours: pipeline data requests extend a
scheduled run's timeout, and a manual run has no timeout. Deploying the
app does not carry this pipeline, so deploy it on its own whenever it
changes.

Deployed runs do not inherit the default development idle timeout. To
limit a scheduled run, configure `--ttl`: it stops after approximately
that many seconds without a pipeline data request. Emitted events do not
reset this timer, so a long processing step can still be interrupted.
An omitted or zero `ttl` disables the timeout. `rocketride deploy run`
starts a manual run without a timeout, even when a schedule is set. A
long-lived pipeline started this way can keep running and billing until
it finishes or someone terminates it. Use a schedule with `ttl` when you
need the automatic timeout.

| | Inside the app | Outside the app |
| --- | --- | --- |
| Where the `.pipe` lives | in the app folder | its own project |
| Who runs it | one instance per signed-in user | one instance for the team |
| When it runs | when the app asks | on its schedule |
| When it stops | finishes, is terminated, or reaches its activity timeout (`ttl`) | finishes, is terminated, or reaches a scheduled run's configured timeout; manual runs have no timeout |
| How it deploys | with the app | separately, `rocketride deploy` |

## Next steps

- [Shell API](/guides/apps): hooks, the descriptor, and the manifest, when
  you code by hand.
- [CLI](/connect/cli): the full command reference.
- Building with a coding agent? The bundle the extension installs already
  contains the complete app reference; point your agent at
  `ROCKETRIDE_APPS.md`.
