Skip to content

Installing an agent

The Hadron portal uses the word "Install" on two different buttons. They're related, they share a verb, and they're emphatically not the same action. This page is the disambiguation.

The two meanings of "install"

Meaning Subject Action API call Result
Org-level install An organization installs an Agent Create a new App from an Agent createApp(orgId, agentId, …) New App row in the org, AppKey, owner AppMember (the creator)
User-level install A user installs an App Join an existing App as a member joinApp(appId) New AppMember row for the user; no new App

The polysemy is deliberate. Both actions feel like "I want this thing on my device / in my account / in my org" — and the PWA analogy holds: "install" works at the OS level (one copy on a device) and at the user level (each profile installs it independently). Hadron borrows that shape: an Org installs the App (one deployment); a User installs themselves into the App.

When does each apply?

Org-level install (createApp)

  • You're an org admin or owner browsing an Agent that hasn't yet been installed into your org.
  • You want a deployment of that Agent in your org — your own App with its own AppKey, its own optional AI override, its own member list.
  • Clicking Install creates the App row plus auto-provisions the AgentOrgGrant that authorizes your org to deploy the Agent.
  • See Building an Agent → Step 3 for the detailed walkthrough; the Install button is the same button.

User-level install (joinApp)

  • You're an end user with a link to an existing App — a coach invited you to their Coaching App, a therapist gave you a code, a company put up a QR code for their employee Brain App.
  • You don't create a new App. The App exists; you're adding yourself to its member list (with whatever role the App allows — mentee, patient, cook, eater, depending on the Agent's installationPolicy.memberRoles).
  • Clicking Install creates an AppMember row for you in that App. Your subscription to the App's Agent is auto-provisioned if you don't have one yet.
  • You may or may not also be an OrgMember of the App's owning org: see Subscriptions and grants for the difference. The user-level install does NOT require OrgMember.

Why one word for two actions?

The user-facing language deliberately conflates the two because, from each user's point of view, the action feels the same: "I'm adding this thing to my space." The system's job is to disambiguate by context — the button next to an Agent on the marketplace creates a new App; the button on a join-link page joins an existing App.

The API surfaces don't share the word: createApp and joinApp are distinct GraphQL mutations with different argument shapes and different error sets. The vocabulary collapse is exclusive to user copy.

Status of the user-level surface

As of spec 023-app-shape:

  • Org-level install — production: the App-creation flow is fully wired in the portal (Agents list → Install button → create form).
  • User-level install — server-side only: the joinApp GraphQL mutation and AppMember.isOrgExternal field are implemented and tested (hadron-server PR #132). The portal surface (a hosted join page that exchanges an invite or link for an AppMember row) lands in a follow-up spec.

For now, third-party Apps that want to enroll users programmatically can call joinApp from their own backend — the mutation is authenticated with an end-user token, not an AppKey, so the user must be logged into Hadron first.

What's next