Skip to content
Linkworld Docs

FAQ

What’s the platform actually doing for me?

Section titled “What’s the platform actually doing for me?”

It runs a per-(tenant, app, version) container, dispatches events to your handlers, holds an audit log of every call, gates tool calls on scope, encrypts your secrets, attributes cost per tenant per app, and gives you a dev console to inspect all of it.

You write code; the platform handles isolation, observability, and the trust boundaries.

Why two SDKs?

Section titled “Why two SDKs?”

Python + TypeScript cover ~85% of partner devs. Both share the same manifest schema and the same handler contract — a CI test (the “drift gate”) asserts both SDKs accept and reject identical YAML fixtures. Pick the one you’d ship in regardless.

Can I use Go / Rust / Ruby?

Section titled “Can I use Go / Rust / Ruby?”

The SDK is HTTP — you can implement the contract yourself. The manifest, the /health + /manifest + /tool/<name> + /event/<type> endpoints, and the /api/mcp/app-tools + /api/mcp/app-secrets client calls are all documented. There’s no official Go/Rust/Ruby SDK yet but nothing stops you.

If you ship one, open a PR — we’d add it to the official supported set.

What’s a “scope”?

Section titled “What’s a “scope”?”

Permissions a tenant grants on install. Your manifest declares required scopes (mail.send, files.read, …). Each platform tool your app calls maps to a scope. The platform refuses tool calls when the scope is missing on either side. See the scope catalog.

Are scopes platform-defined or partner-defined?

Section titled “Are scopes platform-defined or partner-defined?”

Platform-defined. Partners don’t invent scopes; they pick from the catalog. That’s why the catalog matters — it’s the contract surface that gates app capability.

How are secrets stored?

Section titled “How are secrets stored?”

AES-256-GCM at rest, in linkworld_app_secrets. Decrypted only when your container reads via ctx.secrets.get(...). Never displayed after creation — the dev console enforces write-only inputs and the list endpoint omits the encrypted value field entirely.

The encryption key is platform-managed.

Who pays for the platform tools my app calls?

Section titled “Who pays for the platform tools my app calls?”

You pay for tokens consumed inside your handlers (the cost-attribution metrics let you see the bill). The tenant pays for the underlying service the platform integrates with — e.g. you call ctx.tools.call('odoo_create_record', ...) and the tenant’s Odoo license

  • data charges apply.

How does the platform call my container?

Section titled “How does the platform call my container?”

HTTP POST to http://<vm_ip>:<container_port>/tool/<name> or /event/<type>. The container receives JSON, returns JSON.

The reverse direction (your container calling platform tools) goes through https://<platform>/api/mcp/app-tools with a per-(tenant, app) JWT the platform mints at provision time.

What’s the difference between dev-default and tenant-override secrets?

Section titled “What’s the difference between dev-default and tenant-override secrets?”

Dev-default applies to every tenant install. You set it; every tenant sees it (unless they override). Tenant-override is per-install — the tenant admin sets it, and only that tenant’s installs see it. Tenant-override always wins. See Secrets guide.

Can my app store its own data?

Section titled “Can my app store its own data?”

Not in the platform’s database. Bring your own (Postgres, Supabase, SQLite-on-volume, S3 — your call). The platform stores metadata about your app (manifest, versions, audit log) but not your app’s business data.

If you need per-tenant state without running your own DB, use Odoo custom fields (odoo.write scope) — most tenants already have it provisioned.

How do I roll back a bad version?

Section titled “How do I roll back a bad version?”

The rollback button in the app’s Versions tab is read-only today. Workaround: re-run linkworld deploy --version <previous> with the previous tag — that mutates current_version_id back.

What about staging?

Section titled “What about staging?”

The platform doesn’t have first-class staging. Workaround: register a <your-app>-staging slug and deploy non-current versions there. Use a staging tenant for testing.

Could I rebuild the Office Assistant app with the SDK?

Section titled “Could I rebuild the Office Assistant app with the SDK?”

Yes — Office Assistant has been ported to the SDK; the source lives in examples/office-assistant/. Every surface an Office-Assistant-shaped app needs is reachable from a manifest:

  • Custom tools the tenant agent can call (tools: + app.tool())
  • Orchestrator wiring — declare when your tools should fire via workflow hooks (workflows: in the manifest)
  • Specialist agent with its own system prompt (agents: in the manifest — provisioned at install)
  • Dedicated UI mounted at /apps/<slug> via a frontend bundle, plus the platform- rendered right-side panel for chat / settings / files tabs
  • Platform HTTP routes — mount your own endpoints with @app.http_route (OAuth callbacks, webhooks, downloads)
  • Install settings + autonomous visions via install_settings

See Capabilities for the honest scope; the example app is the fastest reference.

How do I get help?

Section titled “How do I get help?”