Skip to content

Build an App ​

A marketplace app is a product of its own, built on Perfox, that a workspace turns on from the App Marketplace. The first one is the CRM. This page is for the team building one: what an app is, how it is put together, how it connects to Perfox, and the steps from an empty repo to an app people open from their workspace.

Start with the app developer skill

In Studio, open Developer → Build an app and press Download the skill. You get a zip with a guide and 11 references that teach Claude Code the whole contract on this page. Unzip it into ~/.claude/skills/ (or your app repo's .claude/skills/) and ask Claude in plain words, for example "add the create handler".

What an app is ​

An app has its own code base, its own data and its own web address, and one deployment serves all the workspaces that turn it on. Perfox is the agent platform; your app is the system of record and the place your users work.

It meets Perfox in exactly five ways, and no other:

#DirectionWhat crossesWhat it's for
1Perfox → your appThe tenant APIPerfox creates, reads, suspends, resumes and cancels your app's copy for a workspace
2A person → your appThe launch tokenOpen in Perfox signs the person in, with a 60-second single-use token. Your app has no passwords and no sign-up
3Your app → PerfoxThe public APIYour app calls /api/v1 with the one key Perfox issues it for that workspace
4Perfox agents → your appYour MCP serverPerfox registers it in the workspace, and agents use your app's tools through it
5Your app → PerfoxThe manifestYour app lists the agents it needs, and Perfox installs them in the workspace

Your app never imports Perfox code, never reads Perfox's database, and never calls Perfox's internal routes.

How an app is structured ​

<workspace> is the workspace's slug and <app> is your app's slug.

AddressWhat lives there
https://<workspace>.<app>.perfox.aiYour app for that workspace, with /auth/launch where people arrive signed in
https://<workspace>.<app>.perfox.ai/mcpYour MCP server for that workspace
https://admin.<app>.perfox.aiYour console and your tenant API (/api/platform/v1). The tenant API answers only here
https://<workspace>-api.perfox.aiThe workspace's Perfox API. Perfox sends it to you when the workspace turns your app on; never build it yourself

The tenant API your app serves, and when Perfox calls it:

CallWhen
POST /tenantsA workspace turns your app on, a retry, or a re-enable
GET /tenants/{id}Perfox reads your copy's state
POST /tenants/{id}/suspendA renewal wasn't paid, or the workspace was suspended
POST /tenants/{id}/resumeA renewal went through, or the workspace is back
POST /tenants/{id}/cancelThe app was cancelled
POST /tenants/{id}/users/{user_id}/revokeA person lost access in Perfox
POST /tenants/{id}/mcp-keyPerfox needs the key it registers your MCP server with
POST /tenants/{id}/databasePerfox hands over the workspace's app database, or a new address for it
GET /manifestPerfox reviews or pins the agents your app needs

Each call waits at most 10 seconds, and a call your app doesn't take is sent again. So every call must be idempotent on the workspace's Perfox tenant id, and every refusal carries { code, message }. Perfox shows your message to the people concerned.

How it connects to Perfox ​

Sign-in. The launch token arrives in the URL fragment at /auth/launch. It is a JWT signed with the workspace's key, carrying:

  • the person: sub, email, name;
  • the claims you check: aud (your slug), tenant_id, jti, and exp (60 seconds after it was issued);
  • an app_role (admin or operator);
  • a relative return_to path.

Your backend checks, in this order:

  1. the signature, against <workspace API>/api/auth/jwks;
  2. aud;
  3. exp;
  4. that this jti was never used before;
  5. that tenant_id is the workspace your address resolves to.

Your key. Perfox issues one sk_ key for each workspace that turns your app on, and sends it at create.

  • Scopes: fixed by your app's listing. The CRM's include conversations, customers, agents, files and webhooks.
  • Who controls it: Perfox. A workspace admin can't rotate it, widen it or delete it.
  • When it ends: it is revoked when your app is cancelled.

Files. Your app keeps no storage of its own: upload through App Files.

Webhooks. Your app's key may subscribe only at your app's own address for that workspace. It sees only its own subscriptions, and they are deleted when your app is cancelled.

Database. A workspace's apps share one app database, which Perfox creates and sends at create as database { name, uri }. Keep to your own collections, and never name, create or drop the database yourself.

The agents your app needs ​

Serve GET /api/platform/v1/manifest with a version and your agents. An agent reaches your app's own tools through an MCP node whose server is @app.

  • Install: Perfox pins one version of your manifest, then installs its agents in each workspace that turns your app on, within the hour. Agents that pass Perfox's publish checks are published.
  • New version: an agent nobody edited is updated. An agent the workspace edited is never overwritten.
  • Dropped agent: one you remove from the manifest is left in place, no longer managed.

Your app's lifecycle ​

Perfox alone decides your app's lifecycle; your app carries out its calls.

What happensWhat Perfox callsWhat your app does
A workspace turns your app oncreate, then the MCP keyMake the workspace's copy
A renewal isn't paidsuspend, as lapsedStay open under a renew banner; notices follow at 30, 60 and 90 days
The renewal is paidresumeOpen again as before
The workspace is suspendedsuspendSuspend the workspace's copy
The app is cancelled (at the end of the paid period, or at once)cancelKeep the data whole for 30 days; a re-enable inside that window restores everything

People can open your app while it is active, lapsed or cancelling.

Build and bring an app live ​

  1. Download the app developer skill from Developer → Build an app and install it for Claude Code.
  2. Perfox adds your app's slug, the scopes its key needs, and its listing.
  3. Build the tenant API, /auth/launch, your MCP server, your manifest and your Perfox client.
  4. Deploy your app.
  5. Perfox saves and tests your app-level key, sets your plans, pins your manifest and publishes your app on the App Marketplace.
  6. On a test workspace: turn the app on, open it, use it, cancel it, and turn it on again within 30 days to check everything comes back.