Skip to main content

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

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 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 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 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 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([...]). 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. Many options accept both snake_case and camelCase names (for example session_fs and sessionFs, builtin_plugin_directories and builtinPluginDirectories, request_handler and requestHandler).
Last modified on November 16, 2026