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

# Client options reference

> Reference of every Laravel Copilot SDK client option, with its default value, environment variable, and how it behaves when you connect in TCP mode.

## Client options reference

You configure the client in `config/copilot.php`.
You can also pass the same options as an array to `Copilot::client()`, `useStdio()` / `useTcp()`, or `new Client([...])`.
This page lists the options in the config file, plus the options you can only pass from code.

## Config file options

| Option | Default | Environment variable | TCP mode |
| - | - | - | - |
| `mode` | `'copilot-cli'` | `COPILOT_MODE` | Shared |
| `url` | `null` | `COPILOT_URL` | Setting it enables TCP mode |
| `cli_path` | `'copilot'` | `COPILOT_CLI_PATH` | Ignored |
| `cli_args` | `[]` | - | Ignored |
| `cwd` | `null` (the app base path) | - | Ignored |
| `log_level` | `'info'` | `COPILOT_LOG_LEVEL` | Ignored |
| `builtin_plugin_directories` | `[]` | - | Shared |
| `timeout` | `60.0` | `COPILOT_TIMEOUT` | Shared |
| `model` | `null` | `COPILOT_MODEL` | Shared |
| `copilot_home` | `null` | `COPILOT_HOME` | Ignored |
| `base_directory` | `null` | `COPILOT_BASE_DIRECTORY` | Ignored |
| `session_fs` | `null` | - | Shared |
| `permission_approve` | `'deny-all'` | `COPILOT_PERMISSION_APPROVE` | Shared (Facade layer) |
| `telemetry` | `null` | - | Ignored |
| `session_idle_timeout_seconds` | `0` | `COPILOT_SESSION_IDLE_TIMEOUT` | Ignored |
| `request_handler` | `null` | - | Shared |

### Connection

* `mode`: the client mode, either `'copilot-cli'` (normal) or `'empty'`. `empty` disables the CLI's implicit features. In this mode you must set a base directory, SessionFs, or a TCP URL explicitly.
* `url`: the URL of an existing Copilot CLI server (for example `tcp://127.0.0.1:12345`). When you set it, the SDK connects to this server instead of starting a new CLI process. See [TCP mode](https://kawax.biz/en/packages/laravel-copilot-sdk/tcp-mode.md) for details.
* `cli_path`: the path to the CLI executable. Set it to `null` to locate the CLI automatically.
* `cli_args`: extra arguments passed when the CLI starts (for example `['--yolo']`).
* `cwd`: the working directory of the CLI process.
* `log_level`: the CLI server log level. Choose from `none`, `error`, `warning`, `info`, `debug`, or `all`.

### Defaults

* `timeout`: the default timeout in seconds for `sendAndWait()`. `Copilot::run()` uses it too.
* `model`: the default model when you create a session without specifying one.
* `permission_approve`: how permission requests are handled automatically when you use the Facade (`Copilot::run()` and similar). Choose `'deny-all'` (deny everything), `'approve-safety'` (approve everything except shell and write), `'approve-all'` (approve everything), or `false` (do not inject a handler). When you use the Client directly, an `onPermissionRequest` handler is always required. See [Permission Requests](https://kawax.biz/en/packages/laravel-copilot-sdk/permission-request.md) for details.

### Data location

* `copilot_home`: the base directory for Copilot data (session state and settings). The SDK passes it to the CLI process it starts as the `COPILOT_HOME` environment variable. When unset, the CLI default (`~/.copilot`) applies.
* `base_directory`: an alias for `copilot_home` that uses the official SDK name. If you set both, `base_directory` wins.
* `session_fs`: the settings for a SessionFs provider that delegates session state (files and SQLite) to your own storage. `initialCwd`, `sessionStatePath`, and `conventions` are required. When you set it, each session must also specify `createSessionFsProvider`.
* `builtin_plugin_directories`: an array of absolute paths to trusted built-in plugin directories. The SDK registers them with the runtime when the client starts. See [Plugin Directories](https://kawax.biz/en/packages/laravel-copilot-sdk/plugin-directories.md) for details.

### Other options

* `telemetry`: an OpenTelemetry settings array (`otlpEndpoint`, `filePath`, `exporterType`, `sourceName`, `captureContent`). The SDK converts it into environment variables for the CLI process it starts. See [OpenTelemetry](https://kawax.biz/en/packages/laravel-copilot-sdk/telemetry.md) for details.
* `session_idle_timeout_seconds`: the server-wide idle timeout for sessions, in seconds. `0` (the default) disables it, so sessions stay alive indefinitely.
* `request_handler`: a `CopilotRequestHandler` or closure that intercepts HTTP requests to the model layer (experimental). It does not apply to WebSocket requests.

## Options not in the config file

The following options are not in the config file, but you can pass them as arguments to `useStdio()`, `Copilot::client()`, or `new Client([...])`.

| Option | Description | TCP mode |
| - | - | - |
| `env` | An array of extra environment variables passed to the CLI process the SDK starts | Ignored |
| `github_token` | The GitHub token used for authentication | Not allowed |
| `use_logged_in_user` | Whether to use the user already logged in to the CLI | Not allowed |
| `installation_confirmation_handler` | A callback that confirms CLI installation | Ignored |
| `entra` | Microsoft Entra authentication settings (`EntraAuthConfig` or an array) | Shared |
| `on_github_telemetry` | A callback that receives GitHub telemetry notifications | Shared |
| `extension_launch_provider` | A callback that resolves how extensions launch | Shared |
| `network` | Sandbox network proxy settings (`scope`, `resolveProxy`, `authenticateNegotiate`) | Shared |

You cannot use `github_token` or `use_logged_in_user` in TCP mode, because the external server manages its own authentication.
If you set either one and connect over TCP, the SDK throws an exception.
For switching tokens at runtime, see also [GitHub token](https://kawax.biz/en/packages/laravel-copilot-sdk/github-token.md).

Many options accept both snake\_case and camelCase names (for example `session_fs` and `sessionFs`, `builtin_plugin_directories` and `builtinPluginDirectories`, `request_handler` and `requestHandler`).


## Related topics

- [TCP mode](https://kawax.biz/en/packages/laravel-copilot-sdk/tcp-mode.md)
- [Official SDK-compatible layer](https://kawax.biz/en/packages/laravel-copilot-sdk/bare-usage.md)
- [HTTP client](https://kawax.biz/en/http-client.md)
- [Configuration reference - VOICEVOX for Laravel](https://kawax.biz/en/packages/laravel-voicevox/configuration.md)
- [HTTP clients and testing in packages](https://kawax.biz/en/advanced/package-http-client.md)


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