Managed agent adoption
Adopt the core Pilot node first; attach a harness action boundary only when in-flight control is wanted.
On this page
Prerequisites
- An existing account in the target organization.
- The administrator or
fleet.commandrole. - A supported host for
pilotctlandpilot-daemon. - Outbound HTTPS access to the organization's management and federation origins.
- Access to the operating-system user that will own the agent runtime. Do not run the installer as root.
Adoption workflow
- Open Connect an agent in the management console.
- Select the real harness that runs the agent. The selection records the expected capability boundary; it does not pretend every harness has universal interception.
- Enter a node display name and choose action interception and
.pilotstate synchronization. Fleet reporting is required. - Select Create one-time command. Pilot allocates the agent ID server-side and returns a high-entropy claim that expires after 15 minutes and is consumed once.
- Run the displayed command on the agent host:
curl -fsSL https://pilotprotocol.network/install.sh | PILOT_ENROLLMENT_TOKEN='<one-time token>' sh -s -- --managed-url https://management.pilotprotocol.network- If action interception is enabled, run the separate, version-pinned harness attachment command shown by the console, for example
npx -y pilotprotocol-mcp@0.2.13 attach --gemini. - Return to the waiting page. Pilot accepts completion only after the allocated identity sends a fresh signed report carrying the exact harness and onboarding-run marker.
- Create and activate a language policy, then attempt a real violating action. The guided flow completes only after it observes a semantic denial for that exact agent before the side effect.
The token is a short-lived bearer secret. Do not put the generated command in tickets, chat, source control, shared shell history, process supervisors, or screenshots.
What the one-time claim installs
The installer downloads the management-authority-pinned managed runtime, then calls pilotctl enterprise adopt. The service returns exactly one delegated node identity plus the public root pin, signed trust bundle, signed bootstrap policy, organization endpoints, adoption options, and run identity. The browser never creates a node key.
The client verifies that the credential, key, trust bundle, policy, tenant, agent ID, and HTTPS authority origins agree. It then atomically writes an owner-only attachment under $HOME/.pilot/managed/:
enterprise-control.json— tenant, endpoints, policy paths, action inventory, rollout, reporting, and state-sync configuration;trust.jsonandpolicy.json— verified signed bootstrap artifacts;agent.seed— the delegated node seed, stored with owner-only permissions;- restart-safe receipt, continuation, and state directories.
The enrollment token is stored server-side only as a hash, consumed before private credential material is released, removed from the process environment, and never reused. Unknown, expired, and consumed tokens return the same generic error.
Optional controls
| Option | When enabled | When disabled |
|---|---|---|
| Fleet connection | Signed health, desired state, rollout, and typed commands. | Not a managed adoption; this option is required. |
| In-flight action control | Selected harness actions wait for signed hosted decisions and produce receipts. | Ordinary harness actions remain unchanged. |
.pilot state visibility | Safe state manifests and revision-checked mutations synchronize over the fleet channel. | No state tree or remote state mutation. |
Core adoption installs the node runtime; it does not install pilot-mcp. Harness attachment is a separate opt-in integration that reads the existing managed attachment. See Harness coverage.
How Pilot verifies adoption
The console does not trust a client-side success message. It checks:
- the report signature against the exact delegated key in tenant trust;
- the server-allocated agent ID;
- the exact harness and one-time onboarding run marker;
- a fresh observation time after the command was issued;
- the policy revision the node reports as active;
- for the guided proof, a durable hosted exchange with a semantic-clause denial for the same agent.
Moving or replacing a node
A managed identity is not portable between organizations. The installer deliberately refuses a new enrollment token when $HOME/.pilot/managed/enterprise-control.json already exists. To replace or move a node, an administrator must retire or revoke the old identity, preserve required evidence, remove the old managed attachment through an approved local decommissioning procedure, and issue a fresh organization-bound adoption. There is no public self-service cross-organization transfer workflow today.
Do not copy agent.seed or the complete managed directory to clone a node. Each runtime instance should receive a distinct delegated identity and appear separately in fleet inventory.
Unmanaged compatibility
Running the ordinary Pilot installer without --managed-url and without an enrollment token preserves unmanaged behavior. Installing a harness adapter without a valid owner-only managed attachment is a zero-side-effect pass-through. Disabling or removing an optional harness boundary should restore the harness's original execution path, subject to that harness's own configuration.