Installing apps

Apps are how capabilities arrive in your tenant. Each app is published by a developer (first-party or community), reviewed by Linkworld’s security gate, and installed by you with explicit consent on the scopes it needs.

Find an app

1. Sign in to https://app.linkworld.ai
2. Open the Apps marketplace from the main nav
3. Browse the catalog or search by name / category
4. Click any app to see:
   • The current published version and what it does
   • The scopes it needs (e.g. email.read, calendar.write) — the security gate refuses any tool call outside this list
   • The install settings the app will collect (see below)
   • Public reviews and the developer’s identity

If you can’t find an app, the marketplace also shows community apps the platform has not bundled — they install the same way but the catalog flags the Community tag so you know it’s third-party code.

Install an app

1. Click Install.
2. The platform shows the consent screen with:
   • Scopes requested — review each one. The platform won’t grant anything that isn’t listed; refusing to grant a scope just means the app’s tool calls in that area get blocked at runtime.
   • Install settings — fields the app needs to function (e.g. a project to attach to, a brand color, an OAuth account). Mandatory fields are marked.
3. Click Approve & install.
4. The app activates: the platform pulls its container image, runs on_install, registers any agents/heartbeats declared in the manifest, and surfaces the app in your sidebar.

Activation is usually < 30 seconds. If it takes longer:

• Check Workspace Control → Health for failing-heartbeat indicators.
• The platform retries on_install automatically; you’ll see the status change to Failed only after several attempts.

Versioning + updates

Apps are immutable per version. When the developer publishes 1.2.0:

• Existing tenants stay on whatever version they installed (no silent upgrades — your tools and data don’t break under you).
• New installs default to the latest version.
• The marketplace surfaces a Update available badge on apps you have installed when a newer version exists.
• Clicking Update runs the new version’s install hook + migrates any settings that have a new schema. The old version’s data and agent memory carry over.

You can also pin to a specific version explicitly if you don’t want auto-upgrade prompts.

What happens during activation

For each app you install, the platform:

1. Pulls the container image to your tenant’s compute pool. This only happens once per (tenant, version) — installs after that reuse the cached image.
2. Provisions agents declared in the manifest. Each agent gets a row in your tenant’s linkworld_agents table with the system prompt, tools allowed, team membership, and any heartbeats.
3. Materializes heartbeats as scheduled rows in linkworld_app_data_feeds — the platform’s unified scheduler picks them up on the next 15-second tick.
4. Sets up vision if the app declares one and you picked a project in the install settings (the autonomous goal-pursuit loop).
5. Fires the on_install lifecycle hook so the app can do its own setup (e.g. wire OAuth tokens, seed records).

All of this happens behind the scenes — you just see the app appear in the sidebar.

Uninstall + paused apps

• Pause stops heartbeats and disables agents but keeps memory and records. Use this when an app is misbehaving — pause first, then decide whether to fix or uninstall.
• Uninstall runs the on_uninstall hook and disables the app. By default it leaves agent memory and tenant records intact (so re-installing doesn’t lose history). Tick delete data to purge.

Multi-app installs are normal

A typical tenant runs 3–10 apps. Office Assistant for personal productivity, a domain-specific app like Sachverständiger or your custom Marketing War Room, plus Workspace Control itself (installed by default — it’s the control plane).

If you install multiple apps from related domains (Marketing + Sales), you’ll likely want them to collaborate — that’s the Wires & grants story.