Skip to content

Latest commit

 

History

History

installable-applications

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Installable applications and UI extensions

This is the complete documentation for the applications catalog: the one-click installable apps in Remote, and the browser extensions they can ship to change the Remote interface itself.

Four things live here, and the differences matter:

  • An application installs software — MySQL, PostgreSQL, Redis — into a container and exposes it on a port.
  • A workspace tool installs software into the project's container and exposes nothing — a CLI, a mount, an agent. It is useful because it is in the workspace, not because anything can connect to it.
  • A UI extension installs nothing anywhere. It is a ui/ directory that runs in the browser and contributes to defined places in the Remote interface: a button in the chat header, a panel, a popup.
  • An application backend is a backend/ directory of Go source. The server compiles its root composition package with imported child packages and runs one process, which the application's ui/ calls. It is how an application adds a server-side feature rather than only a button. A backend may also publish or subscribe to declared server-side events, conventionally owned by backend/lifecycle/ and composed by backend/main.go. With explicit manifest opt-ins, it can also start agent turns, read their results and transcript, expose its own commands to agents, and recover background work after restarts.

One application can be any of these, or several at once. A MySQL application can ship a "Connect" button alongside the database it provisions and a backend that runs the queries behind it; an application that only adds a button ships no container side at all. Applications own their workflow rules and state; the shared runtime supplies ordinary agent execution and checks the captured owner's current access.

Start here

If you want to… Read
Understand how the whole thing fits together 01 — Overview
Add infrastructure to the catalog 03 — Application capabilities, 04 — Install scripts
Add a button, panel, or popup to the Remote UI 07 — Tutorial
Add a server-side feature in Go 15 — Application backends
Look up a field in application.json 02 — application.json reference
Look up an extension API method 06 — Extension API reference
Look up the application backend contract 15 — Application backends
Start/read agent turns or expose application tools 25 — Application agent runtime
Publish or consume backend events 18 — Backend event lifecycle
Know where you are allowed to render 05 — Slots
Know who sees your extension 08 — Scoping and visibility
Make your UI match the app's look 09 — Styling and icons
Test what you built 10 — Fixtures, 11 — Testing
Call the endpoints directly 12 — HTTP API
Understand the trust model 13 — Security model
Fix something that is not working 14 — Troubleshooting
Ship an app to a running server without releasing Remote 16 — Uploaded packages
Ship a new version of an app people already installed 17 — Versions and upgrades

All documents

  1. Overview — the moving parts, and how a request flows through them.
  2. application.json reference — every field, with types and defaults.
  3. Application capabilities — how infra/, backend/, ui/, and skills/ compose.
  4. Install scripts — the contract, the environment, idempotency.
  5. Slots — every place an extension may render, and the context each provides.
  6. Extension API reference — the complete remote object.
  7. Tutorial: build an application — end to end, from empty directory to working button.
  8. Scoping and visibility — install scope is render scope.
  9. Styling and icons — design tokens, theming, the icon field.
  10. Fixtures — ui-playground, ui-sandbox, backend-playground, and how to test with them.
  11. Testing — unit tests, the self-test, and browser verification.
  12. HTTP API — every endpoint, its shape, and its authorization.
  13. Security model — what is enforced, where, and what is not.
  14. Troubleshooting — symptoms, causes, fixes.
  15. Application backends — shipping Go that runs on the server, and calling it from ui/.
  16. Uploaded packages — the same catalog entry, delivered as a .zip at runtime and surviving updates.
  17. Versions and upgrades — how version decides when an installed copy is re-provisioned.
  18. Backend event lifecycle — lifecycle-package ownership, manifest publishers and subscriptions, namespaces, routing, and delivery guarantees.

Additional capability guides:

Conventions in these documents

Paths are given relative to the repository root unless stated otherwise. These documents live in the repository's documentation tree, at docs/dev/installable-applications/, while the thing they describe is a directory of its own at the repository root:

applications/

Keeping the two apart is deliberate: everything under applications/ is embedded into the server binary by //go:embed, and documentation has no business shipping inside a binary. The directive that embeds it is catalog.go at the repository root, in a small module of its own, because go:embed cannot reach above the directory it is written in.

Code references name the file and, where useful, the symbol — registry_ui.go:loadApplicationUI, extensionContributionState.ts:visibleExtensionContributions.