AHP Host

The Agent Host Protocol (AHP) lets you start a listener managed by the Copilot runtime and accept remote clients over WebSocket or GitHub Mission Control. An AHP host is owned by its Client connection. Stopping the listener with Client::stop() or the host’s dispose() does not delete the sessions the host used.

Starting a host

Pass at least one of localServer or githubEnvironment. An authentication mode is also required. To allow anonymous access, you must explicitly pass none.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\AhpHostAuthentication;

$client = Copilot::client();

$host = $client->startAhpHost(
    authentication: AhpHostAuthentication::github(),
    localServer: [],
    allowCreatingNewSessions: true,
    workspace: '/workspace/project',
);

echo $host->url;

localServer: [] uses a loopback address and a free port. githubEnvironment requires github authentication. Treat the token returned by the host as a connection secret. workspace is the working directory used by the AHP host. The Copilot runtime resolves this path on the host where the runtime runs, so it may differ from the path inside your Laravel application. When you omit it, the SDK does not include workspace in the RPC call and the runtime keeps its existing behavior.

Authentication modes

AhpHostAuthentication::github() authenticates with a GitHub account. You can combine it with githubEnvironment.
AhpHostAuthentication::none() explicitly disables authentication.
AhpHostAuthentication::custom() validates admission tokens with your own application logic. It requires a stable owner identity and a validation callback.

The custom authentication callback receives a HostValidateAuthenticationRequest containing the decrypted admission token, and a CancellationToken that signals cancellation. On success, return the identity and a future expiresAt in RFC3339 format. To reject the token, return null. The identity must exactly match requireIdentity.

use Revolution\Copilot\Types\AhpHostAuthentication;
use Revolution\Copilot\Types\Rpc\HostAuthenticationResult;
use Revolution\Copilot\Types\Rpc\HostValidateAuthenticationRequest;
use Revolution\Copilot\Support\CancellationToken;

$authentication = AhpHostAuthentication::custom(
    requireIdentity: 'team-123',
    authenticate: function (
        HostValidateAuthenticationRequest $request,
        CancellationToken $signal,
    ): ?HostAuthenticationResult {
        if ($signal->isCancellationRequested()) {
            return null;
        }

        $identity = validateAdmissionToken($request->token);

        if ($identity !== 'team-123') {
            return null;
        }

        return new HostAuthenticationResult(
            identity: $identity,
            expiresAt: '2099-01-01T00:00:00Z',
        );
    },
);

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
);

The admission token is a separate credential from the GitHub token or provider token used for inference. Do not store it in logs or session config. The callback’s signal is cancelled when the host receives host.authenticationCancelled or shuts down. If the callback calls external services, register abort handling with onCancellationRequested().

Session creation policy

allowCreatingNewSessions sets the initial policy for remote clients creating new sessions. When omitted, remote session creation is denied. The policy does not apply to sessions created by the owning application, published sessions, or existing connections. To change the policy while the host is running, call the host’s setSessionCreationPolicy(). The new policy applies to requests that arrive after the change is acknowledged. Creation requests that were already accepted can complete. Connected clients are not disconnected.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

When using RPC directly, call $client->rpc()->host()->setSessionCreationPolicy() and pass a HostSetSessionCreationPolicyRequest with the hostId and the new setting.

Application-owned sessions

Pass createSession and resumeSession callbacks to hand requests from the AHP host to your application’s Client. Each callback receives a HostMaterializeSessionRequest containing the runtime-verified HostSessionAuthentication and the host-provided config, plus a CancellationToken for cooperative cancellation. Return a session created or resumed with the same Client.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\CancellationToken;
use Revolution\Copilot\Types\Rpc\HostMaterializeSessionRequest;
use Revolution\Copilot\Support\PermissionHandler;

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
    createSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        return $client->createSession([
            ...($request->config ?? []),
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    resumeSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        $sessionId = $request->config['sessionId'];

        return $client->resumeSession($sessionId, [
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    onSessionReleased: function (CopilotSession $session): void {
        // Application-side cleanup when AHP participation ends
    },
);

onSessionReleased receives the session whose participation ended. The SDK does not disconnect or destroy the session. HostMaterializeSessionRequest::$authentication is a trusted identity verified by the host, not client input. Still perform any tenant or user authorization you need inside the callback.

Session catalog and shutdown

$host->publishSession('session-id');
$sessions = $host->listSessions();
$host->unpublishSession('session-id');
$host->dispose();

Unpublishing removes the session from the AHP catalog. It does not delete local history or stop running work. dispose() stops the listener but does not delete related sessions.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

AHP Host

AHP Host

Starting a host

Authentication modes

Session creation policy

Application-owned sessions

Session catalog and shutdown

​AHP Host

​Starting a host

​Authentication modes

​Session creation policy

​Application-owned sessions

​Session catalog and shutdown

​Related documentation

AHP Host

Starting a host

Authentication modes

Session creation policy

Application-owned sessions

Session catalog and shutdown

Related documentation