Keys and sign-in
Sign in from your client and it acts as you, with your saved logins. Scripts, servers and shared agents use one of your organization's API keys.
Create a key (admins)
- Sign in to pilotfish and open Org settings, then API keys.
- Choose Create key, and name it after what it's for.
- Copy it into the client's settings in place of
pf_YOUR_KEY.
Manage and check keys
A key belongs to one shared project, picked when you create it and movable later. It runs tasks for your organization there, paid from its credits, without any person's saved logins: your users' logins belong to their identities. It sees only the tasks it started, one at a time, and is never an admin. Admins can show it again, rotate or revoke it from the same page; rotate a key when someone who had it leaves. Open a key to see what it spent and its tasks, and to give it an allowance: a spending limit, after which its tasks pause until an admin raises it. Check one without an agent:
PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --checkIn Windows PowerShell:
$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --checkSign in a terminal
Clients that start pilotfish's relay (Codex CLI and other stdio clients), on your laptop or over SSH, sign in once with no key: run npx -y @gaiventures/pilotfish-mcp-managed login, open the link it prints on any device (your phone works), check that the page shows the same code, and choose Allow. The relay keeps the sign-in in a file only you can read and renews it by itself. logout signs that computer out.
Signing in or a key
| Signed in from your client | An organization API key | |
|---|---|---|
| Acts as | You | The organization |
| Project | Personal, until you switch | Its own shared project |
| Saved logins and saved tasks | Yours, in Personal | None: your users' logins are identities |
| Tasks it sees | Yours; an admin can read everyone's in the organization | Only those it started |
| Spending limit | Your allowance, if an admin set one | The key's allowance, if an admin set one |
| Best for | You at your own agent | Scripts, servers, shared agents |
Knowing when an end user's login is saved
Give a login link a webhookUrl (in the MCP, webhook_url) and your server gets a signed identity.login_saved event as each site's login is saved: the identity, your user id, the site, the account, its credential id, and whether the link is now used up. Never the username or password. A sign-in an identity keeps during a task sends the same event to that task's webhook.
One place and one device per end user
All of an identity's sites see one residential IP from the same city, and one device, as one person's browsing would. A provider holds a residential IP for a day at most, so pilotfish renews it between tasks, never during one, in the same city and on the same device.
Codes and sign-ins for your end users
An authenticator code is typed by pilotfish when the identity's login has its key. A code sent by text or email, a sign-in or a security check pauses the task on the end user: the reply says Waiting for the end user of identity idn_… with an Answer here: link, and the job.needs_input webhook names the identity. Send them the link; they answer on pilotfish's page and the task carries on. A sign-in typed there is kept for the identity when it keeps sign-ins.
Personal API keys
Admins (the primary admin included) can make a key of their own in Org settings → API keys: pick the project Personal (you). It acts as them, in their Personal project, and only they can see or manage it. A member can have them too once an admin turns on Allow personal API keys on that person's page in Org settings (turning it off revokes their keys). Otherwise members connect their AI tool by signing in. Admins see each person's key usage.
Your organization
Everyone is in one organization, and its tasks are paid from its credits. Signing up names a new one, with you as its primary admin; an emailed invitation joins an existing one.
- Primary admin: everything an admin does, and only they can hand the role on or delete the organization.
- Admins: add credits, the card and auto reload, the monthly limit and overage, and the organization's credit history (Org settings → Credits); people and their roles, allowances, API keys and shared projects; everyone's tasks and spending, by person and key (Org settings → Usage).
- Members: run their own tasks on the organization's credits, within any allowance an admin gives them. Admins can see their tasks.
Usage in the sidebar is always your own: your spend and tasks, and your allowance when you have one (what's left of it shows in the sidebar). The organization's balance, credit history and everyone's usage are its admins' only.
Each person, each key and each identity runs one task at a time. A long task checks in after a set amount of spending ($1 by default) with what it found; carry on with follow_up. get_usage shows what you can spend.