Marketplace

The ObjectOS marketplace lets you install pre-built apps into a running runtime — no build step, no restart, no source checkout. It's the fastest way to put real software in front of users on day one.

How it works

The marketplace client is the open-source @objectstack/cloud-connection package. Cloud-managed environments and the self-hosted ObjectOS image ship it wired up out of the box; a stack you assemble yourself enables it with a few lines of config:

import {
  MarketplaceProxyPlugin,
  MarketplaceInstallLocalPlugin,
  RuntimeConfigPlugin,
  resolveCloudUrl,
} from '@objectstack/cloud-connection';

const catalogUrl = resolveCloudUrl(); // OS_CLOUD_URL; 'off' disables

plugins: [
  ...(catalogUrl ? [
    new MarketplaceProxyPlugin({ controlPlaneUrl: catalogUrl }),
    new MarketplaceInstallLocalPlugin({ controlPlaneUrl: catalogUrl }),
  ] : []),
  new RuntimeConfigPlugin({ controlPlaneUrl: '', singleEnvironment: true, installLocal: true }),
]

The browse/install mechanism is open; the catalog service (org catalogs, review, paid distribution) is provided by whichever control plane OS_CLOUD_URL points at. Once an app is installed it lives in your runtime's own kernel — nothing at runtime depends on the catalog staying reachable.

When you open Console (/_console/), the marketplace tab queries the configured app catalog and shows installable apps.

You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install
                                                  ↓
                                       Artifact merged into kernel
                                                  ↓
                                       Console re-renders with new
                                       objects / views / permissions
                                                  ↓
                                       Done — no restart

Catalogs

The catalog source is configured via the marketplace plugin or env vars; see Runtime Configuration.

What's in the default catalog

These apps are ready to install with one click in Console:

Source is at github.com/objectstack-ai/templates — clone any of them as a starting point for a custom app.

Install flow

1. Open Console — http://localhost:3000/_console/
2. Sign in — if no account exists yet, register one at /_account/register
3. Navigate to the marketplace tab
4. Pick an app, click Install
5. Reload Console — the new app's objects, views, and flows appear

Behind the scenes, the marketplace fetches the app's compiled artifact, merges it into the running kernel, and registers its objects with ObjectQL. Seed data (if the app defines it) is inserted on first install.

Uninstall

From Console → Marketplace → installed app → Uninstall. The app's objects are removed from the kernel and its tables are marked for cleanup (data is retained by default; you choose whether to drop tables).

Publishing your own app

Anything you build with os init can become a marketplace app.

os init my-app -t app --install
cd my-app
# ... write objects, views, etc. ...
os compile                                    # → dist/objectstack.json
os package publish                            # publish to a catalog

To publish to the public catalog, you'll need a registry account (os login). To publish to a private catalog, point OS_PACKAGE_REGISTRY at your own.

Versioning

Every published app is immutable. Updates produce a new version. The runtime tracks installed version + available updates per app. Users see an "Update available" badge in Console when a new version is published to a catalog they're tracking.

Installing from the CLI

Console is the primary install surface, but the same install-local endpoint is scriptable for CI and air-gapped operations:

# Catalog mode — the runtime resolves the package from its configured catalog
os package install com.acme.crm --runtime http://localhost:3000 \
  --email admin@example.com --password …

# Air-gapped mode — send a compiled artifact inline, no catalog round-trip
os package install ./dist/objectstack.json --runtime http://localhost:3000 \
  --email admin@example.com --password …

The credentials are an account on the target runtime (not your cloud login) — the same authorization Console install uses.

Permissions

Installing apps requires the manage_marketplace system permission — by default only members of the Setup Administrator permission set have it. Regular users see the marketplace as read-only.

Air-gapped marketplaces

For deployments without internet egress, run a local catalog server inside your network and point ObjectOS at it. See Air-gapped for the topology.

What the marketplace is not

• Not a code distribution channel. Published apps are compiled artifacts — they describe data + UI + flows declaratively. They don't ship arbitrary JavaScript.
• Not a sandbox. An installed app has the same access to your database as anything else in the kernel — review the artifact before installing apps from untrusted sources.
• Not a payment platform (yet). Apps in the public catalog are free Apache-2.0. Commercial / paid distribution is on the roadmap.