Remote and sandbox
Scope: SessionRpc (per-session operations tied to a Session) For an overview of RPC and the list of all RPC pages, see RPC.remote (experimental: remote session support)
use Revolution\Copilot\Enums\RemoteSessionMode;
use Revolution\Copilot\Types\Rpc\RemoteEnableRequest;
use Revolution\Copilot\Types\Rpc\RemoteEnableResult;
// Enable a remote session
// When run in a GitHub repository's working directory,
// it returns a URL you can use to access the session from GitHub web or mobile
$result = $session->rpc()->remote()->enable();
// $result->remoteSteerable - Whether remote steering is enabled
// $result->url - GitHub frontend URL (may be null)
// Enable with a mode
// RemoteSessionMode::Off - Local only (default)
// RemoteSessionMode::Export - Export session events to GitHub (no remote steering)
// RemoteSessionMode::On - Enable both export and remote steering
$result = $session->rpc()->remote()->enable(new RemoteEnableRequest(
mode: RemoteSessionMode::Export,
));
// Disable the remote session
$session->rpc()->remote()->disable();
// Connect to a remote session (experimental)
use Revolution\Copilot\Types\Rpc\ConnectRemoteSessionParams;
$connected = $session->rpc()->remote()->connectRemoteSession(new ConnectRemoteSessionParams(
sessionId: 'remote-session-id',
));
// $connected->sessionId - ID of the connected session
// $connected->metadata - ConnectedRemoteSessionMetadata object
notifySteerableChanged().
$session->rpc()->remote()->notifySteerableChanged(['remoteSteerable' => true]);
sandbox (experimental: sandbox control)
// Check the host's sandbox support before creating a session
$hostSupport = $client->rpc()->sandbox()->getHostSupport();
// $hostSupport->supported, $hostSupport->reason, $hostSupport->capabilities
// Check whether a Proxy CA is needed and whether installation is supported
$proxyCa = $client->rpc()->sandboxProxyCa();
$relevant = $proxyCa->checkRelevance(['enabled' => true]);
$installable = $proxyCa->checkInstallationSupport();
use Revolution\Copilot\Types\Rpc\SandboxDisableForSessionRequest;
use Revolution\Copilot\Types\Rpc\SandboxGrantPathForRequestRequest;
use Revolution\Copilot\Types\Rpc\SessionSandboxGetRemoteMcpEgressRequest;
// Get the sandbox enforcement status
$status = $session->rpc()->sandbox()->getEnforcementStatus();
// Check whether enforcement can be applied to new sandbox admissions
$session->rpc()->sandbox()->ensureEnforcementAvailable();
// Decide egress for a remote MCP endpoint
$egress = $session->rpc()->sandbox()->getRemoteMcpEgress(
new SessionSandboxGetRemoteMcpEgressRequest(
secretConfigDir: '/path/to/mcp-secrets',
url: 'https://mcp.example.com',
),
);
// deniedReason is set only when denied, and proxyUrl only when routed through an allowed proxy
// Credentials that may be usable in new sandbox shells (values aren't returned)
$credentials = $session->rpc()->sandbox()->getCredentialSuggestions();
// $credentials->suggestions is an array of SandboxCredentialSuggestion
// Empty array when the sandbox is disabled or there are no suggestions. Settings and network permissions aren't changed.
// Approve a pending sandbox bypass permission request and disable the sandbox for the whole session
$result = $session->rpc()->sandbox()->disableForSession(new SandboxDisableForSessionRequest(requestId: $requestId));
// $result->success, $result->enabled
// Approve the path grant (sandboxPathGrant) offered by a pending sandbox escalation permission request,
// add that path to the session's sandbox policy, and have the blocked operation
// re-run inside the sandbox
$result = $session->rpc()->sandbox()->grantPathForRequest(new SandboxGrantPathForRequestRequest(requestId: $requestId));
// Array input also works: ->grantPathForRequest(['requestId' => $requestId])
// $result->success
// Fails if the request is no longer pending, didn't come with a sandboxPathGrant,
// or the grant is invalid under the current managed policy.
// This least-privilege approach allows only a specific path and is preferred over disableForSession(), which disables the whole session.
// The path isn't persisted (it applies only to this session and isn't carried over to later sessions).
// Hosts that save sandbox settings can save the path themselves if needed.
$request['sandboxPathGrant'] is present, call this with the requestId of the pending request. Because this RPC itself responds to the permission request, return PermissionDecision::noResult() on success so that no normal response is sent.
if (isset($request['sandboxPathGrant'])) {
$result = $session->rpc()->sandbox()->grantPathForRequest([
'requestId' => $requestId,
]);
return $result->success
? PermissionDecision::noResult()
: PermissionDecision::reject();
}