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

# TCP 모드

> Laravel Copilot SDK에서 미리 기동한 Copilot CLI 서버에 접속하여 낮은 오버헤드로 공유 운영하는 방법을 설명합니다.

## TCP 모드

일반적으로 SDK는 각 요청마다 새로운 Copilot CLI 프로세스를 기동합니다(stdio 모드).
TCP 모드를 사용하면 사전에 기동해 둔 Copilot CLI 서버에 접속할 수 있습니다.

## TCP 모드의 이점

* **성능 향상**: 프로세스 기동 오버헤드가 없음
* **리소스 공유**: 여러 Laravel 프로세스에서 동일한 CLI 서버를 공유 가능
* **프로세스 관리**: Laravel Forge / Laravel Cloud에서 백그라운드 프로세스로 관리 가능
* **배포 대응**: 배포 시의 자동 재시작에 대응 가능

## 사용법

### 1. Copilot CLI 서버 기동

```shell theme={null}
copilot --headless --port 12345
```

### 2. 환경 변수 설정

```dotenv theme={null}
COPILOT_URL=tcp://127.0.0.1:12345
# COPILOT_URL=http://127.0.0.1:12345
# COPILOT_URL=127.0.0.1:12345
# COPILOT_URL=12345
# COPILOT_URL=127.0.0.1
# COPILOT_URL=localhost
```

이것만으로 SDK는 stdio 모드에서 TCP 모드로 자동 전환됩니다.

* `tcp://`는 임의입니다. `http://`나 스키마 없이도 동작합니다.
* 포트만 지정할 수도 있습니다. 그 경우 호스트는 자동으로 `127.0.0.1`이 됩니다.
* 호스트만 지정하는 것은 `127.0.0.1`과 `localhost`만 유효합니다. 그 경우 포트는 기본값 `12345`가 됩니다.

## 설정 파일

`config/copilot.php`에서 TCP 접속을 설정할 수 있습니다.

```php theme={null}
return [
    // TCP 접속처 URL(설정하면 TCP 모드가 됨)
    'url' => env('COPILOT_URL'),

    // 다음은 stdio 모드일 때만 사용됨
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // 양 모드 공통
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];
```

`COPILOT_URL`(`cli_url`)과 `COPILOT_CLI_PATH`를 모두 설정한 경우 TCP 모드가 우선됩니다.

## 실행 시 모드 전환

일반적으로는 설정 파일에 따라 TCP 모드인지 stdio 모드인지가 자동으로 선택됩니다.
코드 내에서 명시적으로 전환할 수도 있습니다.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

// TCP 모드로 전환
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// 생략 시에는 설정 파일 값을 사용
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// stdio 모드로 전환
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// 생략 시에는 설정 파일 값을 사용
// 양 모드를 설정한 경우 TCP가 우선이므로 일시적인 오버라이드에 사용 가능
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');
```

서버에 따라서는 TCP 모드에서 정상적으로 동작하지 않는 경우가 있습니다.
큐 처리는 TCP 모드로, HTTP 요청 내의 처리는 stdio 모드로처럼 구분해 사용할 수도 있습니다.

## Laravel Forge / Laravel Cloud에서의 운영

### Laravel Forge

1. **Daemon 작성**: Forge 관리 화면에서 Daemon을 작성합니다.

   ```
   Command: copilot --headless --port 12345
   User: forge
   Directory: /home/forge/your-app
   ```

2. **환경 변수 설정**: `.env`에 `COPILOT_URL`을 추가합니다.

3. **배포 시 재시작**: 배포 스크립트에서 Daemon을 재시작합니다.

현재 Forge 환경에서는 불필요한 경우가 있습니다.

```shell theme={null}
sudo supervisorctl restart daemon-123456:*
```

### Laravel Cloud

Laravel Cloud의 워커 기능을 사용해 백그라운드 프로세스로 실행할 수 있습니다.

자세한 내용은 [Laravel Cloud에서의 사용법](/ko/packages/laravel-copilot-sdk/laravel-cloud)을 참고하세요.

## 주의사항

### 보안

<Warning>
  TCP 서버는 가능한 한 로컬 바인드(`127.0.0.1`)를 사용하세요.
  외부에 공개할 경우 방화벽 설정을 적절히 해주세요.
</Warning>

### 재접속

현재 버전에는 자동 재접속 기능이 없습니다. 접속이 끊어지면 예외가 던져집니다.

### 현재 모드 확인

프로그램 내에서 클라이언트가 어떤 모드인지 확인할 수 있습니다.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

if ($client->isTcpMode()) {
    // TCP 모드
} else {
    // stdio 모드
}
```

## 트러블슈팅

### 접속할 수 없음

1. Copilot CLI 서버가 기동되어 있는지 확인

```shell theme={null}
ps aux | grep copilot
```

2. 포트가 올바른지 확인

```shell theme={null}
netstat -an | grep 12345
```

3. 방화벽 설정 확인

### 타임아웃 에러

`config/copilot.php`의 `timeout` 값을 늘려 주세요.

```php theme={null}
'timeout' => 120, // 2분
```

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


## Related topics

- [Laravel Cloud - GitHub Copilot SDK for Laravel](/ko/packages/laravel-copilot-sdk/laravel-cloud.md)
- [GitHub 토큰](/ko/packages/laravel-copilot-sdk/github-token.md)
- [세션 라이프사이클 이벤트](/ko/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [Remote Sessions](/ko/packages/laravel-copilot-sdk/remote-sessions.md)
- [인증 - GitHub Copilot SDK for Laravel](/ko/packages/laravel-copilot-sdk/auth.md)