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

# Cloud Sessions

> 로컬 Copilot CLI가 아닌 GitHub 호스트 환경에서 세션을 실행하는 Cloud Sessions의 사용법을 설명합니다.

## Cloud Sessions

Cloud Sessions는 로컬 Copilot CLI 프로세스가 아니라 GitHub 측 호스트 환경에서 세션을 실행하는 기능입니다. Mission Control에서 태스크가 예약되고, 클라우드 측의 `copilot-agent`가 접속하여 처리를 진행합니다.

일반 Remote Sessions는 "로컬에서 실행되는 세션을 GitHub Web/모바일에서 볼 수 있도록 하는" 기능입니다. 실행 장소 자체를 GitHub 호스트 환경으로 하려면 Cloud Sessions를 사용합니다.

## 사전 조건

* 사용자가 Cloud Agent를 이용할 수 있는 Copilot 권한을 가지고 있음
* GitHub 토큰 또는 로그인된 Copilot CLI 사용자로 인증할 수 있음
* 가능하다면 GitHub 저장소 정보를 연결
* 조직 정책에서 클라우드 실행과 원격 열람이 허용되어 있음

## 기본 사용법

`SessionConfig`의 `cloud`에 `CloudSessionOptions`를 지정합니다. 저장소 정보는 SDK 타입상 임의이지만, Mission Control과 클라우드 에이전트에 컨텍스트를 전달하기 위해 지정하는 것을 권장합니다.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $session->sendAndWait(prompt: 'README를 요약해줘');
}, config: new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),
));
```

배열로도 지정할 수 있습니다.

```php theme={null}
Copilot::run(
    prompt: '이 저장소의 테스트 방침을 확인해줘',
    config: [
        'cloud' => [
            'repository' => [
                'owner' => 'myorg',
                'name' => 'myrepo',
                'branch' => 'main',
            ],
        ],
    ],
);
```

## 최초 프롬프트를 보내는 타이밍

Cloud Session은 2단계로 초기화됩니다. `session.create`는 Mission Control에서 태스크가 예약된 시점에 리턴되지만, 클라우드 측 `copilot-agent`가 접속해 `session.start`를 발행하기까지 약간의 시간이 있습니다.

최초 프롬프트를 확실하게 전달하려면 먼저 이벤트를 구독하고, `producer`가 `copilot-agent`의 `session.start`를 확인한 후에 전송하세요.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    streaming: true,
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(owner: 'myorg', name: 'myrepo'),
    ),
);

Copilot::start(function (CopilotSession $session): void {
    $cloudAgentStarted = false;

    foreach ($session->stream(timeout: 30.0) as $event) {
        if (
            $event->is(SessionEventType::SESSION_START)
            && $event->data('producer') === 'copilot-agent'
        ) {
            $cloudAgentStarted = true;
            break;
        }
    }

    if (! $cloudAgentStarted) {
        throw new RuntimeException('Cloud session did not become ready.');
    }

    $session->sendAndWait(prompt: 'README를 요약해줘');
}, config: $config);
```

실제 앱에서는 큐나 비동기 처리 측에서 `session.start` 확인 후에 프롬프트를 보내는 구성으로 하면 다루기 쉽습니다.

## Remote Sessions와의 차이

| 기능              | 실행 장소         | 주요 용도                                    |
| --------------- | ------------- | ---------------------------------------- |
| Remote Sessions | 로컬 또는 자체 서버   | Web/모바일에서 기존 세션을 열람, 조작                  |
| Cloud Sessions  | GitHub 호스트 환경 | 사용자 단말이나 자체 서버에서 Copilot CLI를 실행하지 않고 처리 |

## 주의점

* Cloud Sessions는 권한과 조직 정책의 영향을 받습니다
* `streaming: true`로 하면 `assistant.message_delta` 등의 실시간 이벤트를 받을 수 있습니다
* 권한 요청의 처리는 일반 세션과 동일합니다. Laravel 버전 Facade 경유로는 기본적으로 deny-all이므로 필요에 따라 `PermissionHandler::approveSafety()` 등을 지정하세요

## 참고

* [Remote Sessions](/ko/packages/laravel-copilot-sdk/remote-sessions)
* [SessionConfig](/ko/packages/laravel-copilot-sdk/session-config)
* [스트리밍 이벤트](/ko/packages/laravel-copilot-sdk/streaming-events)

<Info>
  최신 정보는 [GitHub 저장소](https://github.com/invokable/laravel-copilot-sdk)를 참고하세요.
</Info>


## Related topics

- [Remote Sessions](/ko/packages/laravel-copilot-sdk/remote-sessions.md)
- [SessionConfig](/ko/packages/laravel-copilot-sdk/session-config.md)
- [스트리밍 이벤트](/ko/packages/laravel-copilot-sdk/streaming-events.md)
- [GitHub Copilot SDK for Laravel](/ko/packages/laravel-copilot-sdk/index.md)
- [Laravel Cloud CLI — 터미널에서 Laravel Cloud 조작하기](/ko/blog/laravel-cloud-cli.md)