Reference
Connect a client
Base URL · no API key
Pick one — these are alternatives, not steps.
Install the private CAonce per device
HTTPS here is issued by a private authority. A browser can be clicked
through; curl, Node and the ACP launcher cannot — they refuse
until the root is installed. Installing into the OS store is not
always enough: Firefox always, and Chrome on Linux, keep their
own trust store and ignore the system one.
VS Codethe ACP extension, four steps
The extension is not an HTTP client — it spawns
codex-gateway-acp on the machine your code is on, and
that process calls the gateway. So 127.0.0.1 there
means your machine; use the address above. Needs Python 3.11+,
Node 20+, VS Code 1.100+.
the steps below follow this choice
- Build the launcher where your code is:
- Package and install the client, then reload VS Code:
- Add to user
settings.json —
launcherPath absolute, on your machine:
- Open a trusted folder → Codex Gateway in the Activity
Bar → send a task. Stuck? Codex Gateway: Show ACP Logs.
WSLonly when the code is in the distribution
Windows itself needs no WSL: select Windows above and the
four steps run as they are. Use this block only when the repository is in
the WSL file system and you open it with the VS Code WSL remote. Then run
all four steps inside the distribution.
- Install everything in the distribution — repository,
uv, Node.js, launcher. Set launcherPath to the
path in the distribution.
code --install-extension needs wget.
Without it, the command builds the VSIX file and then gives the error
"Failed to download the VS Code server":
sudo apt-get update && sudo apt-get install -y wget
As an alternative, press Ctrl+Shift+P, select
Extensions: Install from VSIX… in the WSL window, and
install the file there.- WSL does not use the Windows VPN resolver. A name can
resolve in the browser but not in the distribution, so the launcher
cannot reach the gateway. Add the host:
curlcheck it from a shell
Bifrost & friendskeyless provider block
SSH tunnelwhen there is no network route
The gateway also listens on the
host's loopback. Nothing new is exposed, no certificate involved: