> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# AHP Host

> Start an Agent Host Protocol (AHP) host with Laravel Copilot SDK and configure authentication, session creation policy, and application-owned sessions.

## 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`.

```php theme={null}
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`.

```php theme={null}
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.

```php theme={null}
$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`.

```php theme={null}
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

```php theme={null}
$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.

## Related documentation

* [RPC](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
* [Remote Sessions](https://kawax.biz/en/packages/laravel-copilot-sdk/remote-sessions.md)


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
- [Password reset](https://kawax.biz/en/passwords.md)
- [Laravel Reverb](https://kawax.biz/en/reverb.md)
- [Authentication - GitHub Copilot SDK for Laravel](https://kawax.biz/en/packages/laravel-copilot-sdk/auth.md)
- [Laravel Sail](https://kawax.biz/en/sail.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.