Skip to main content

TCP mode

Normally the SDK starts a new Copilot CLI process for every request (stdio mode). TCP mode lets you connect to a Copilot CLI server that’s already running.

Advantages of TCP mode

  • Better performance: no process-start overhead.
  • Resource sharing: multiple Laravel processes can share the same CLI server.
  • Process management: the CLI can be managed as a background process by Laravel Forge / Laravel Cloud.
  • Deploy-friendly: automatic restart at deploy time is supported.

How to use it

1. Start a Copilot CLI server

2. Set an environment variable

That alone switches the SDK from stdio mode to TCP mode automatically.
  • tcp:// is optional. http:// or no scheme also works.
  • You can specify just a port; the host defaults to 127.0.0.1.
  • Specifying just a host works only with 127.0.0.1 and localhost. The port defaults to 12345.

Config file

You can configure the TCP connection in config/copilot.php.
If both COPILOT_URL (cli_url) and COPILOT_CLI_PATH are set, TCP mode takes precedence.

Switching modes at runtime

Normally the config file selects TCP or stdio mode automatically. You can also switch modes explicitly in code.
Depending on the server, TCP mode may not work correctly. You can also mix the two — for example, TCP mode for queue processing and stdio mode inside HTTP requests.

Running on Laravel Forge / Laravel Cloud

Laravel Forge

  1. Create a daemon: create a daemon from the Forge admin UI.
  2. Set the environment variable: add COPILOT_URL to .env.
  3. Restart on deploy: restart the daemon from your deploy script.
Depending on the current Forge environment, this step may not be needed.

Laravel Cloud

You can run it as a background process using Laravel Cloud’s worker feature. See Using it on Laravel Cloud for details.

Notes

Security

Bind the TCP server locally (127.0.0.1) whenever possible. If you expose it externally, configure your firewall appropriately.

Reconnection

There is no automatic reconnect in the current version. If the connection drops, an exception is thrown.

Checking the current mode

You can check which mode the client is in from your code.

Troubleshooting

Cannot connect

  1. Check whether the Copilot CLI server is running.
  1. Verify the port.
  1. Check firewall settings.

Timeout errors

Increase the timeout value in config/copilot.php.
For the latest updates, see the GitHub repository.
Last modified on August 2, 2026