Client options reference
You configure the client inconfig/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'.emptydisables 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 exampletcp://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 tonullto 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 fromnone,error,warning,info,debug, orall.
Defaults
timeout: the default timeout in seconds forsendAndWait().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), orfalse(do not inject a handler). When you use the Client directly, anonPermissionRequesthandler 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 theCOPILOT_HOMEenvironment variable. When unset, the CLI default (~/.copilot) applies.base_directory: an alias forcopilot_homethat uses the official SDK name. If you set both,base_directorywins.session_fs: the settings for a SessionFs provider that delegates session state (files and SQLite) to your own storage.initialCwd,sessionStatePath, andconventionsare required. When you set it, each session must also specifycreateSessionFsProvider.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: aCopilotRequestHandleror 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 touseStdio(), 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).