Register an app
Registering adds a running app to a Shell's launchpad. It uses two values — a remote entry (the app UI's base URL, e.g. http://localhost:4175; the Shell appends /remoteEntry.js) and a slug (the path it mounts at) — and needs that remoteEntry.js reachable.
Which route: developer or admin?
Your role picks the route, and the route changes the slug and who sees the app. Register the same two ways in either — the Shell UI, or the veni CLI.
Anyone with the developer role. The slug is prefixed with your username (hrm → /alice-hrm) and the app is a private draft only you see — so many developers each register their own hrm without colliding.
Needs the admin role. The slug is unprefixed (hrm → /hrm) and the app can be published to the whole org.
In the Shell UI
1. Flip the sidebar toggle End-user → Developer (developers only, dev env).
You land on My Apps.
2. Register a local app:
Local UI URL http://localhost:4175
Display name HRM
slug hrm (required for a localhost URL)
3. Register app → mounts at /<your-username>-hrm as a private draft you own.1. Apps → Quick Integrate.
2. Paste the two values:
Remote entry http://localhost:4175
Slug hrm
3. Tick "Allow local URL" for a localhost entry → Register → mounts at /hrm.With the veni CLI
From the app root — it also rewrites api/.env for that Shell and records it in veni.json, so restart the API afterward. Needs the veni CLI.
veni register --shell http://localhost:3000 # self-service: uses your PAT → /<you>-<slug>, private
veni register --shell http://localhost:3000 --user admin # admin (password login) → unprefixed /<slug>A PAT is always self-service
A personal access token carries no roles the CLI can read, so plain veni register takes the developer route even for an admin — you get /<you>-<slug>, private. Pass --user <admin> to log in and register platform-wide.
Which Shell?
The --shell URL (and, in the UI, which Shell you're signed into) picks the target environment:
| Target | --shell | Opens at | Notes |
|---|---|---|---|
| Local | http://localhost:3000 | http://localhost:5173/<slug> | Sign in with a seeded account |
| Cloud (Dev) | https://shell-api.dev.venizia.ai | https://veni.dev.venizia.ai/<slug> | Needs the developer role — see Cloud setup |
Values (example apps)
| App | Remote entry | Slug | Opens at |
|---|---|---|---|
| HRM | http://localhost:4175 | hrm | /hrm |
| Drive | http://localhost:4176 | drive | /drive |
"Opens at" is the admin (unprefixed) path; the developer self-service route mounts the same app at /<your-username>-<slug>.
Full walkthroughs
- Local setup — bring up the platform, run an app, register it.
- Cloud setup — run your app locally and register it against Dev.
Common snags
| Symptom | Fix |
|---|---|
| App missing from the launchpad | The app must be running; register it and reload the Shell. |
Registered, but not at /hrm | The self-service route prefixes your username → /<you>-hrm, a private draft. Register as an admin (UI Quick Integrate, or CLI --user <admin>) for the unprefixed /hrm. |
| No My Apps in the sidebar | It's behind the Developer-mode toggle (sidebar) — visible only with the developer role in a dev environment. Quick Integrate instead needs the admin role. |
| Localhost entry rejected | Enable "Allow local URL" when registering. |
| App loads but "not signed in" | Persistent: the Shell's RSA key (APP_ENV_JWT_PRIVATE_KEY) is unset — remote apps can't verify its tokens. Only on a cold load, fine after a refresh: the token-broadcast race, not the key. |
| Registered on Cloud but blocked | Your Dev account needs the developer role (request it from the platform team). |