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

# Modalità TCP

> Descrive come connetterti a un server Copilot CLI pre-avviato con Laravel Copilot SDK e usarlo in condivisione con basso overhead.

## Modalità TCP

Di norma l'SDK avvia un nuovo processo Copilot CLI per ogni richiesta (modalità stdio).
Con la modalità TCP puoi connetterti a un server Copilot CLI avviato in anticipo.

## Vantaggi della modalità TCP

* **Miglioramento delle performance**: nessun overhead di avvio processo
* **Condivisione delle risorse**: più processi Laravel possono condividere lo stesso server CLI
* **Gestione del processo**: gestibile come processo in background con Laravel Forge / Laravel Cloud
* **Adatto al deploy**: supporta il riavvio automatico durante il deploy

## Uso

### 1. Avvia il server Copilot CLI

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

### 2. Imposta la variabile d'ambiente

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

Con questo, l'SDK passa automaticamente da stdio a TCP.

* `tcp://` è opzionale. Funziona anche con `http://` o senza schema.
* Puoi specificare solo la porta. In tal caso l'host è automaticamente `127.0.0.1`.
* La specifica del solo host è valida solo per `127.0.0.1` e `localhost`. In tal caso la porta di default è `12345`.

## File di configurazione

Puoi configurare la connessione TCP in `config/copilot.php`.

```php theme={null}
return [
    // URL di destinazione TCP (se impostato attiva la modalità TCP)
    'url' => env('COPILOT_URL'),

    // I successivi vengono usati solo in modalità stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Comune a entrambe le modalità
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];
```

Se imposti sia `COPILOT_URL` (`cli_url`) sia `COPILOT_CLI_PATH`, ha priorità la modalità TCP.

## Cambio di modalità a runtime

Di norma la modalità TCP o stdio viene scelta automaticamente in base al file di configurazione.
Puoi anche cambiarla esplicitamente nel codice.

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

// Passa alla modalità TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Se omessa, usa il valore del file di configurazione
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// Passa alla modalità stdio
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// Se omesso, usa il valore del file di configurazione
// Se sono impostate entrambe le modalità ha priorità TCP, quindi è utile per un override temporaneo
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');
```

Con alcuni server la modalità TCP potrebbe non funzionare correttamente.
È anche possibile alternare: modalità TCP per le queue, modalità stdio all'interno delle richieste HTTP.

## Uso con Laravel Forge / Laravel Cloud

### Laravel Forge

1. **Crea un Daemon**: crea un Daemon dalla dashboard Forge.

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

2. **Imposta la variabile d'ambiente**: aggiungi `COPILOT_URL` in `.env`.

3. **Riavvio al deploy**: riavvia il Daemon nello script di deploy.

Con l'attuale ambiente Forge potrebbe non essere necessario.

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

### Laravel Cloud

Puoi eseguirlo come processo in background usando la funzionalità worker di Laravel Cloud.

Per i dettagli consulta [Uso su Laravel Cloud](/it/packages/laravel-copilot-sdk/laravel-cloud).

## Note

### Sicurezza

<Warning>
  Usa per quanto possibile il bind locale (`127.0.0.1`) per il server TCP.
  Se lo esponi pubblicamente, configura in modo appropriato il firewall.
</Warning>

### Riconnessione

La versione attuale non ha una riconnessione automatica. Se la connessione cade viene sollevata un'eccezione.

### Verifica della modalità corrente

Nel codice puoi verificare in che modalità è il client.

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

$client = Copilot::client();

if ($client->isTcpMode()) {
    // modalità TCP
} else {
    // modalità stdio
}
```

## Troubleshooting

### Connessione fallita

1. Verifica che il server Copilot CLI sia in esecuzione

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

2. Verifica che la porta sia corretta

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

3. Verifica la configurazione del firewall

### Errore di timeout

Aumenta il valore di `timeout` in `config/copilot.php`.

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

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Concurrency](/it/packages/laravel-copilot-sdk/concurrency.md)
- [Laravel Cloud - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/laravel-cloud.md)
- [Eventi del ciclo di vita della sessione](/it/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [Token GitHub](/it/packages/laravel-copilot-sdk/github-token.md)
- [Autenticazione - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/auth.md)