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

# Remote and sandbox

> Use SessionRpc in Laravel Copilot SDK to control remote sessions and the sandbox.

## 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](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md).

## remote (experimental: remote session support)

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

To tell the runtime that a session's remote steerability has changed, use `notifySteerableChanged()`.

```php theme={null}
$session->rpc()->remote()->notifySteerableChanged(['remoteSteerable' => true]);
```

For details, see [Remote Sessions](https://kawax.biz/en/packages/laravel-copilot-sdk/remote-sessions.md).

## sandbox (experimental: sandbox control)

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

In your permission handler, when `$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.

```php theme={null}
if (isset($request['sandboxPathGrant'])) {
    $result = $session->rpc()->sandbox()->grantPathForRequest([
        'requestId' => $requestId,
    ]);

    return $result->success
        ? PermissionDecision::noResult()
        : PermissionDecision::reject();
}
```


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
- [SessionRpc overview](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/session-overview.md)
- [Remote Sessions](https://kawax.biz/en/packages/laravel-copilot-sdk/remote-sessions.md)
- [ServerRpc overview](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [MCP](https://kawax.biz/en/packages/laravel-copilot-sdk/mcp.md)


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