Implementer playbook

Set up the business's pools, hand control to its owner, and connect its existing agents through remote MCP. PUDL's hosted product requires no customer-installed PUDL software or continuously running customer gateway. The owner makes the choices about access, hosted credentials and chargeable tools. Keep keys and sign-in links out of chats, tickets, pool records and shared notes.

1. Prepare your firm

  1. Sign in at Organizations. Under Set up businesses for others, enter your firm's name and click Create an implementer organization.
  2. Open your implementer dashboard. It shows your implementer code, clients and invitations. For an existing business, give its owner your code; they invite your firm from Implementers, and you click Accept on your dashboard.
  3. On your account, add passkeys on two devices you can recover independently, such as a laptop and a security key. Do this before your firm takes on its second client.

Once your firm's grants reach more than one business, its owners and admins must confirm their session with a passkey to open client pages. Sensitive actions may require another confirmation after 15 minutes. If you lose every passkey, contact the operator at abuse@pudl.ai for identity-verified recovery. Existing passkeys and browser sessions are revoked, then a replacement added after a new email sign-in waits 48 hours. Keep two independent passkeys so recovery is rarely needed.

2. Create the client's business

  1. On the implementer dashboard, find Set up a business, enter the client's name and click Set it up. Check the business name before continuing.
  2. The business starts in setup. Your firm has admin access, and no owner exists until the client's owner accepts the ownership invite. You never become their owner.
  3. Open Connect PUDL in a compatible existing agent client and use remote MCP. Select this business and only the required pools during normal PUDL consent. No local signing key, claim_link, PUDL package or background service is required for this path.

Keep each client's connection and selected workspace distinct. An agent acts for one organization at a time; check its workspace and accessible pools before doing work. The main pool is for ordinary team data. The sources pool is restricted to owners, admins and authorized admin implementers. Scoped pool creation and joining require eligible direct owner/admin authority; an implementer grant is not a blanket permission to perform those actions.

3. Prepare the pooled workflow

Agree on what the business wants an agent to accomplish. Pool its relevant data, instructions, skills, workflow definitions and tool connection descriptions. Prefer a small, checkable workflow before adding more sources. The agent orchestrates the work; PUDL supplies shared data and approved online tool access.

For a shared workflow, identify each required tool and whose provider account it should use. Reusing a workflow does not transfer its publisher's credentials or tool permissions. The recipient supplies their own keys privately or uses a separately authorized hosted connection within the current recipient rules. Do not promise arbitrary cross-workspace use of another person's provider account.

Existing local systems may participate by reading an ordinary pool request when available, doing locally authorized work and posting a result that references the request. This needs no PUDL-specific bridge, scheduler or command runner. Pool content never grants execution authority, and an offline participant cannot promise an immediate response.

4. Add and approve sources

Use reviewed HTTP MCP connection descriptions for the hosted path. A description names an endpoint and required credential fields; it never contains real keys. Have the already authorized remote agent add the reviewed connection description to the intended private pool using its available connection or contribution tools. Check the actual library status when choosing a description: research drafts and vendor names are not evidence of working integrations. This prepares a record only; it does not contact the provider or approve execution. The Legacy sources page and its library-copy workflow are for existing gateways, not the hosted setup sequence.

You may prepare descriptions during setup. Hosted custody and execution approval wait for a direct business owner, after handoff if the business has none yet. An implementer or admin cannot use the owner's private management flow on their behalf. Do not collect the owner's keys or treat a legacy web source approval as hosted execution permission.

Where Hosted connections is enabled, the owner selects an exact connection version, stores its required keys privately, discovers the current tool catalogue, and approves an eligible agent and selected tools. In a business, the recipient must be a direct member's agent with access to the connection's pool; in a personal workspace, it must be the holder's own agent. A firm working through an implementer grant is not automatically eligible to use the owner's hosted credentials.

Only enable tools that change data, contact people or incur provider charges when the owner deliberately approves those abilities. PUDL enforces permissions and request limits; generic tool costs are governed by provider spending controls, not a PUDL monetary ceiling. Managed imports have their own approved caps. A changed connection or tool catalogue may need fresh review; do not silently approve it for the owner.

Existing gateway approvals and lock recovery — legacy reference

This subsection preserves the existing gateway operating instructions and the #4-add-and-approve-sources recovery link. It is not a requirement for hosted onboarding and does not authorize a custody migration.

On legacy Sources, review the endpoint or pinned package, select only intended tools, set the warning about text written by outsiders accurately, and choose Approve. HTTP sources accept web approval when the existing gateway allows it. After handoff, implementer approvals normally wait for the owner, except for sites named by published recipes. During setup they can take effect, and the owner reviews them at handoff. A stdio source runs a package and always needs approval at the gateway's terminal; use the exact displayed command with that business's sources pool. Web approval cannot replace that step. Apply update changes the copied connection and requires approval again.

The gateway daemon and terminal approval command can safely update the same approval file. If an approval reports that the file is busy, retry after the other command finishes. If a writer crashed and the message persists, stop the gateway and every terminal process using that volume, remove only approved.json.lock/owner.json and the now-empty approved.json.lock directory beside the approval file, then restart and retry. Do not remove a lock while any writer is running, and do not run two gateway daemons against one volume. The lock is deliberately never removed just because it is old.

5. Prepare the owner's account connections

Give the owner a list of required services, intended accounts, requested tools and any expected provider costs. Use the owner guide's hosted connection steps. The owner signs in recently and enters keys directly into PUDL's private fields after taking ownership. Do not put real credentials in workflow records, credential templates, screenshots or AI context. A template lists requirements; it is not a running executor.

Where enabled, the dedicated Connect GitHub with repository and tool permissions browser flow handles GitHub sign-in and repository selection. Authorizing the GitHub App is a provider-account action, not software installation on a customer machine. Select the repositories, tools and write boundaries deliberately, then have the owner approve each eligible PUDL agent separately.

Do not substitute a generic vendor OAuth promise for the supported keyed HTTP or dedicated GitHub flows. A disabled feature or a recipe with unsupported authentication is a capability gap to report, not a reason to ask the customer to install a gateway. Keep unresolved connections out of the working-source list. The business can still use its pooled data while provider setup is pending.

6. Hand ownership to the business

  1. On the business's Overview, enter The owner's email address and click Send the ownership invite. The link works once for 14 days; sending another replaces it. If the page says Invite not sent, resolve email delivery and resend.
  2. The owner opens the email and signs in with that same address. A person from your implementer organization cannot accept ownership for the client.
  3. On Take ownership, review Who has access together. Under Review people added during setup, the owner checks each displayed person and role to retain. Member email addresses identify the people. Unchecked people lose access, including unused invitations and guest access they approved; changed roles are not silently retained.
  4. Review each connection destination. If legacy web approvals exist, the owner chooses Keep or Turn off. Explain any existing terminal-approved packages separately. Hosted credentials and agent tool approvals remain separate owner actions after acceptance.
  5. Explain the receipt-sharing checkbox: it is initially checked and shares totals once at least three businesses report. The owner chooses, then clicks Accept and become the owner.

Your firm remains an admin implementer until its grant expires or is revoked. The owner can end it from Implementers. After handoff, only the business's direct owners and admins invite people or change roles. An existing active gateway keeps working; pending implementer replacements require owner approval. Confirm the dashboard says owner accepted, and give the owner the owner guide.

7. Connect the first AI app

Have the owner use Connect PUDL and Connect your AI. Follow the current client instructions instead of relying on old provider menu names. The client must actually support remote HTTP MCP and PUDL's authorization flow; internet access alone is not enough.

Start with reading and only the intended business pools. Ask: “Use PUDL to show my workspace and accessible pools. Do not change anything.” If writing is needed and approved, save one small piece of requested data to an explicit pool and read it back. Pool creation and joining are separately approved capabilities, not implied by reading or contributing.

For tools, request the necessary discovery and invocation permissions and complete the owner's separate exact-agent/tool approval. Ask the agent to list connection status, then use one harmless approved read and verify the result at the provider. Inspect Hosted connections, AI connections and Activity. Do not call a connection working if it needs credentials, approval, unsupported authentication or operator enablement.

8. Leave an operable business

Record the business and pools, working sources, provider accounts, permission choices, spending limits, support contact and recovery procedure without credentials. The owner should know how to revoke an AI installation, an individual hosted tool permission, a whole connection and your firm's grant. Review the owner's export and deletion controls; exports never contain provider keys or tokens.

Name who owns any required backups and who has verified restoration. Hosted infrastructure and its backups are the PUDL operator's responsibility; customer vendor accounts and independent copies still need their own recovery arrangements. Do not invent a backup guarantee from an export or an untested provider plan.

When the engagement ends, the owner uses Implementers → Revoke → Revoke now and reviews People, AI connections and Hosted connections. Rotate keys your firm could have seen and revoke unnecessary authorizations at each provider. Existing gateway deployments need the additional legacy cleanup below. There is no customer PUDL service to install or keep running for a new hosted setup.

Existing gateway deployment and custody — legacy reference

These instructions are retained for existing deployments, outside the hosted product's supported launch setup. They do not require new customers to install software and do not force existing customers to move their keys. Any migration needs a separate review of permissions, credential custody and provider access.

An existing gateway holds vendor credentials and connects outward to PUDL over a WebSocket. It needs no inbound port, public domain or certificate, but it must stay running to serve tools. Its hosting account, container, persistent volume and backups should be controlled by the business. Use one gateway daemon and one volume per business; never share or clone that volume into another business. Keep the volume mounted at /data and the existing restart policy. A host outage is retried during startup and after connection; changed host identity or invalid enrollment requires operator attention.

Retained deployment references are the gateway release checklist and deployment templates. A dashboard image name is not proof of a published image. The image provides package isolation that running pudl-mcp gateway directly does not. The templates alone do not establish a backup policy; /data contains secrets and must be protected.

For a reviewed replacement of an existing gateway, Gateway → Add a gateway generates a private enrollment command. Its token is shown once, works once and expires after 24 hours. A replacement enrolled by an implementer after handoff waits for an owner to choose Make it the business's gateway now. Once an authorized replacement is ready and takes over, the old gateway is revoked. Web approvals transfer; terminal approvals must be repeated.

For legacy keyed sources, the owner checks the named gateway and who enrolled it, enters the restricted key in Sources, and chooses Seal and send to that gateway. The browser encrypts it for the gateway; JavaScript and an online gateway are required. Supported legacy vendor OAuth uses Sign in to the displayed provider domain; the gateway retains the tokens. Public sources may need neither keys nor sign-in. Wait for ready and verify one approved read. These legacy forms are distinct from Hosted connections.

Gateway revocation does not erase its disk or stop its cloud deployment. If your firm controls it, revoke it before the owner enters replacement keys; rotate credentials it could read, revoke old provider sign-ins, stop the retired container, delete the volume and handle its backups under the agreed retention policy. PUDL exports exclude gateway credentials. Follow the approval lock recovery instructions only when every writer using the volume is stopped.

Your account · Read as Markdown