From 2f2a51574ec5e291f6e01c7d505b07693a64653d Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 19:23:14 +0100 Subject: [PATCH 01/12] Fix Codex CLI command example --- docs/workflows/codex_cli_setup.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index e8f136e..c7fd5c0 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -83,11 +83,15 @@ This is where you choose **Option A (API key)** or **Option B (browser login)**. -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ -e OPENAI_API_KEY="sk-your-api-key" \ - -e CODEX_CLI_COMMAND="codex run --config /opt/agent/runtime/network_policy.json" \ + -e CODEX_CLI_COMMAND="codex run" \ ai-agent-toolkit:latest ``` -The agent will start automatically and use your API key. +The agent will start automatically and use your API key. The container entrypoint +applies the network policy declared in `config/agent_config.json`, so no extra +flags are required when launching `codex run`. Advanced users can still add +`--config key=value` overrides to `CODEX_CLI_COMMAND` if they need to tweak +Codex CLI behaviour. --- @@ -99,12 +103,16 @@ The agent will start automatically and use your API key. docker run -d \ -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ - -e CODEX_CLI_COMMAND="codex run --config /opt/agent/runtime/network_policy.json" \ + -e CODEX_CLI_COMMAND="codex run" \ ai-agent-toolkit:latest ``` > The `-d` flag keeps the container running in the background. + > Network restrictions from `agent_config.json` are still enforced by the + > entrypoint; customize `CODEX_CLI_COMMAND` only if you need additional Codex + > CLI overrides. + 2. Find the container ID: ```bash From 8ce8db19917e779e4ecd8411a2ddf64930880047 Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 19:30:36 +0100 Subject: [PATCH 02/12] Improve browser login workflow and add live-mount guidance --- docs/workflows/codex_cli_setup.md | 44 ++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index c7fd5c0..0a8273c 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -97,13 +97,15 @@ Codex CLI behaviour. ### 🌐 Option B — Browser login (if you don’t have an API key) -1. Start the container **without** the API key: +1. Start the container **without** the API key and leave `CODEX_CLI_COMMAND` + blank so the entrypoint does not try to run the Codex CLI before you finish + logging in: ```bash docker run -d \ -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ - -e CODEX_CLI_COMMAND="codex run" \ + -e CODEX_CLI_COMMAND="" \ ai-agent-toolkit:latest ``` @@ -141,6 +143,16 @@ Codex CLI behaviour. -v "$PWD/.codex:/root/.config/codex" ``` +6. Start the Codex agent once login succeeds. Because you left + `CODEX_CLI_COMMAND` empty when the container booted, launch the CLI manually: + + ```bash + docker exec -it codex run + ``` + + > Alternatively, stop the temporary container (`docker stop `) and + > restart it with `-e CODEX_CLI_COMMAND="codex run"` now that your login is cached. + --- ## 5. Verify Codex CLI connectivity @@ -163,7 +175,33 @@ If it prints a valid response, you’re ready to go! --- -## 6. Updating the configuration +## 6. Iterating on agent code without rebuilding the image + +When you edit JavaScript in `scripts/` or tweak shell helpers, you do **not** +need to rebuild the Docker image. Bind-mount the source directories into the +container so it always runs your local files: + +```bash +docker run --rm \ + -v "$PWD/config:/opt/agent/config" \ + -v "$PWD/scripts:/opt/agent/scripts" \ + -v "$PWD/docker/entrypoint.sh:/entrypoint.sh" \ + -v "$PWD/workspaces:/workspaces" \ + -e OPENAI_API_KEY="sk-your-api-key" \ + -e CODEX_CLI_COMMAND="codex run" \ + ai-agent-toolkit:latest +``` + +- Changes you make locally are reflected the next time the CLI runs. +- Rebuild the image only when you modify dependencies in the Dockerfile itself + (for example, adding new apt or npm packages). + +You can apply the same volume mounts to the browser-login flow by adding the +`-v` lines from above to the Option B command. + +--- + +## 7. Updating the configuration - Any changes to `agent_config.json` take effect the next time you start the container. - To test different access levels, edit `internet_access.mode` and toggle `allow_unrestricted_mode`. From cf3feeb23c980b69883cf65312cfee26b9fc1b8c Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 19:48:47 +0100 Subject: [PATCH 03/12] Keep container running when Codex command is empty --- docs/workflows/codex_cli_setup.md | 12 ++++++++++-- scripts/bootstrap_agent.js | 9 ++++++++- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 0a8273c..7c4532b 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -99,7 +99,8 @@ Codex CLI behaviour. 1. Start the container **without** the API key and leave `CODEX_CLI_COMMAND` blank so the entrypoint does not try to run the Codex CLI before you finish - logging in: + logging in. When `CODEX_CLI_COMMAND` is empty the container now stays alive + in an idle state so you can exec into it afterward: ```bash docker run -d \ @@ -109,7 +110,8 @@ Codex CLI behaviour. ai-agent-toolkit:latest ``` - > The `-d` flag keeps the container running in the background. + > The `-d` flag keeps the container running in the background, and the + > entrypoint will idle instead of exiting so you can authenticate. > Network restrictions from `agent_config.json` are still enforced by the > entrypoint; customize `CODEX_CLI_COMMAND` only if you need additional Codex @@ -153,6 +155,12 @@ Codex CLI behaviour. > Alternatively, stop the temporary container (`docker stop `) and > restart it with `-e CODEX_CLI_COMMAND="codex run"` now that your login is cached. +7. When you are done with the idle container, stop it to clean up resources: + + ```bash + docker stop + ``` + --- ## 5. Verify Codex CLI connectivity diff --git a/scripts/bootstrap_agent.js b/scripts/bootstrap_agent.js index 6fb7907..e12dfd8 100755 --- a/scripts/bootstrap_agent.js +++ b/scripts/bootstrap_agent.js @@ -219,7 +219,14 @@ function runSeedDataScript(config) { function launchAgent() { const command = process.env.CODEX_CLI_COMMAND; if (!command) { - console.log("CODEX_CLI_COMMAND not set; skipping Codex CLI launch."); + console.log( + "CODEX_CLI_COMMAND not set; container will remain idle so you can log in via `docker exec`." + ); + try { + runInherit("tail", ["-f", "/dev/null"]); + } catch (e) { + console.warn(`Idle wait exited unexpectedly: ${e.message}`); + } return; } const res = spawnSync(command, { stdio: "inherit", shell: true }); From 810d26b3f5aeddb01efababa7d47a0921d36a21c Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 21:23:26 +0100 Subject: [PATCH 04/12] Document named container workflow for Codex CLI --- docs/workflows/codex_cli_setup.md | 39 ++++++++++++++++--------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 7c4532b..bd02496 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -2,9 +2,12 @@ > **Note:** This guide describes a Docker-based setup for the `codex` CLI, specific to this `ai-agent-toolkit` project. For information on installing and running the `codex` CLI directly on your machine, please refer to the [official documentation](https://github.com/openai/codex). -This guide explains how to prepare the Docker image and start the Codex CLI agent with the configuration system in this repository. +This guide explains how to prepare the Docker image and start the Codex CLI agent with the configuration system in this repository. It is written for **beginners** — even if you are new to Docker or not very technical, you can follow along step by step. +> **If you hit an error:** copy the exact command you ran and its full output. +> Sharing both together makes it much easier to diagnose issues. + --- ## 1. What you need before starting @@ -79,7 +82,7 @@ This is where you choose **Option A (API key)** or **Option B (browser login)**. 2. Run: ```bash - docker run --rm \ + docker run --rm --name codex-agent \ -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ -e OPENAI_API_KEY="sk-your-api-key" \ @@ -87,6 +90,9 @@ This is where you choose **Option A (API key)** or **Option B (browser login)**. ai-agent-toolkit:latest ``` + > If you already have a container called `codex-agent`, stop and remove it + > first with `docker rm -f codex-agent`. + The agent will start automatically and use your API key. The container entrypoint applies the network policy declared in `config/agent_config.json`, so no extra flags are required when launching `codex run`. Advanced users can still add @@ -103,7 +109,7 @@ Codex CLI behaviour. in an idle state so you can exec into it afterward: ```bash - docker run -d \ + docker run -d --name codex-agent \ -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ -e CODEX_CLI_COMMAND="" \ @@ -117,19 +123,13 @@ Codex CLI behaviour. > entrypoint; customize `CODEX_CLI_COMMAND` only if you need additional Codex > CLI overrides. -2. Find the container ID: - - ```bash - docker ps - ``` - -3. Open a shell inside the container: +2. Open a shell inside the container by referring to the name you just set: ```bash - docker exec -it /bin/bash + docker exec -it codex-agent /bin/bash ``` -4. Log in with your browser: +3. Log in with your browser: ```bash codex auth login @@ -139,26 +139,27 @@ Codex CLI behaviour. - Open the URL on your host machine, sign in to OpenAI, and paste the code. - Once confirmed, the CLI is authenticated. -5. (Optional) To make login persist across runs, add this volume mount: +4. (Optional) To make login persist across runs, add this volume mount: ```bash -v "$PWD/.codex:/root/.config/codex" ``` -6. Start the Codex agent once login succeeds. Because you left +5. Start the Codex agent once login succeeds. Because you left `CODEX_CLI_COMMAND` empty when the container booted, launch the CLI manually: ```bash - docker exec -it codex run + docker exec -it codex-agent codex run ``` - > Alternatively, stop the temporary container (`docker stop `) and + > Alternatively, stop the temporary container (`docker stop codex-agent && docker rm codex-agent`) and > restart it with `-e CODEX_CLI_COMMAND="codex run"` now that your login is cached. -7. When you are done with the idle container, stop it to clean up resources: +6. When you are done with the idle container, stop it to clean up resources: ```bash - docker stop + docker stop codex-agent + docker rm codex-agent ``` --- @@ -170,7 +171,7 @@ Once authenticated (via API key or browser login): 1. Attach to the container shell if you’re not already inside: ```bash - docker exec -it /bin/bash + docker exec -it codex-agent /bin/bash ``` 2. Run a test command: From e91875926c113d71f1f819927648698cece0824f Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 21:36:34 +0100 Subject: [PATCH 05/12] Document port publishing for Codex browser login --- docs/workflows/codex_cli_setup.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index bd02496..2a564c0 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -105,11 +105,14 @@ Codex CLI behaviour. 1. Start the container **without** the API key and leave `CODEX_CLI_COMMAND` blank so the entrypoint does not try to run the Codex CLI before you finish - logging in. When `CODEX_CLI_COMMAND` is empty the container now stays alive - in an idle state so you can exec into it afterward: + logging in. Publish port `1455` so your host browser can reach the callback + endpoint that the CLI spins up during authentication. When + `CODEX_CLI_COMMAND` is empty the container now stays alive in an idle state + so you can exec into it afterward: ```bash docker run -d --name codex-agent \ + -p 1455:1455 \ -v "$PWD/config:/opt/agent/config" \ -v "$PWD/workspaces:/workspaces" \ -e CODEX_CLI_COMMAND="" \ @@ -129,15 +132,19 @@ Codex CLI behaviour. docker exec -it codex-agent /bin/bash ``` -3. Log in with your browser: +3. Log in with your browser. Bind the login server to `0.0.0.0` (so Docker can + forward traffic from your host) and pin the port to `1455` to match the + publish rule above: ```bash - codex auth login + codex auth login --bind 0.0.0.0 --port 1455 ``` - You’ll see a short code and a URL. - Open the URL on your host machine, sign in to OpenAI, and paste the code. - - Once confirmed, the CLI is authenticated. + - Once confirmed, the CLI is authenticated. If the browser callback hangs, + double-check that the container is still running and that port `1455` is + exposed on your `docker run` command. 4. (Optional) To make login persist across runs, add this volume mount: @@ -146,7 +153,8 @@ Codex CLI behaviour. ``` 5. Start the Codex agent once login succeeds. Because you left - `CODEX_CLI_COMMAND` empty when the container booted, launch the CLI manually: + `CODEX_CLI_COMMAND` empty when the container booted, launch the CLI manually + (the login flags are not needed anymore): ```bash docker exec -it codex-agent codex run From d96b9d7ccf37473bd1e5e9f20e2ea09fcf209b9d Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 21:42:07 +0100 Subject: [PATCH 06/12] Clarify when to rebuild or restart Docker --- docs/workflows/codex_cli_setup.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 2a564c0..0936c80 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -213,6 +213,15 @@ docker run --rm \ - Rebuild the image only when you modify dependencies in the Dockerfile itself (for example, adding new apt or npm packages). +> **Do I need to rebuild or restart after every change?** +> +> - **No rebuild** is required for JS/shell edits that are bind-mounted — just +> rerun `codex run` (or restart the container) to pick up the new code. +> - **Restart the container** if you change `agent_config.json`; the entrypoint +> reads it at startup. +> - **Rebuild the image** only when you touch `docker/Dockerfile` or install new +> global dependencies inside the image. + You can apply the same volume mounts to the browser-login flow by adding the `-v` lines from above to the Option B command. From 1e659a3b51a2d04ef556b46cd452c74c000fb828 Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 22:58:00 +0100 Subject: [PATCH 07/12] Expose OAuth callback port and document mapping --- docker/Dockerfile | 1 + docs/workflows/codex_cli_setup.md | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index 83ba4c6..d0f02ec 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -15,5 +15,6 @@ COPY scripts ${AGENT_HOME}/scripts COPY config ${AGENT_HOME}/config COPY docker/entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ${AGENT_HOME}/scripts/bootstrap_agent.js ${AGENT_HOME}/scripts/seed_data.sh +EXPOSE 1455 VOLUME ["/workspaces", "${AGENT_HOME}/config"] ENTRYPOINT ["/entrypoint.sh"] diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 0936c80..ba5cf06 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -117,11 +117,15 @@ Codex CLI behaviour. -v "$PWD/workspaces:/workspaces" \ -e CODEX_CLI_COMMAND="" \ ai-agent-toolkit:latest - ``` + ``` > The `-d` flag keeps the container running in the background, and the > entrypoint will idle instead of exiting so you can authenticate. + > The Docker image exposes port `1455` by default; publishing it with + > `-p 1455:1455` forwards the browser callback traffic from your host into the + > container so the CLI can finish the OAuth flow. + > Network restrictions from `agent_config.json` are still enforced by the > entrypoint; customize `CODEX_CLI_COMMAND` only if you need additional Codex > CLI overrides. From ed43e06f5ae412aa4a92f794dd5bb699cf0c14b1 Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 22:58:06 +0100 Subject: [PATCH 08/12] Document container isolation guidance --- docs/workflows/codex_cli_setup.md | 33 +++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index ba5cf06..280a8bd 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -5,6 +5,27 @@ This guide explains how to prepare the Docker image and start the Codex CLI agent with the configuration system in this repository. It is written for **beginners** — even if you are new to Docker or not very technical, you can follow along step by step. +--- + +## Why this workflow exists + +Running the agent inside Docker keeps it isolated from your host machine. Even +when you grant the model unrestricted internet access (for example to let it +research libraries), the container boundary keeps prompt-injection payloads from +touching your local files or secrets—only the bind-mounted workspace is +visible. To stay safe: + +- Create a dedicated `workspaces/` directory for the repos the agent should + modify. Do **not** mount your entire home folder. +- Leave the default network policy (`internet_access.mode: "codex_common"`) + unless you explicitly need full internet access. +- If you do enable unrestricted access, set `allow_unrestricted_mode` to + `true` in `agent_config.json` and keep sensitive data outside the bind + mounts. + +No container setup can make AI agents perfectly safe, but this workflow gives +you a strong isolation layer while keeping the ergonomics of the Codex CLI. + > **If you hit an error:** copy the exact command you ran and its full output. > Sharing both together makes it much easier to diagnose issues. @@ -49,7 +70,10 @@ It is written for **beginners** — even if you are new to Docker or not very te - Set `internet_access.mode`: - `"offline"` → no internet access. - `"codex_common"` → access to a safe allowlist (recommended). - - `"unrestricted"` → full internet access (**not recommended** unless you know the risks). + - `"unrestricted"` → full internet access (use only when you understand the risks). + - Leave `allow_unrestricted_mode` as `false` unless you truly need the + agent online without restrictions. If you flip it to `true`, double-check + that the container is the only place the agent can reach your files. --- @@ -90,6 +114,10 @@ This is where you choose **Option A (API key)** or **Option B (browser login)**. ai-agent-toolkit:latest ``` + > The agent now runs entirely inside Docker. Prompt-injection payloads cannot + > escape the container unless you mount additional host folders, so keep the + > bind mounts limited to the project workspace. + > If you already have a container called `codex-agent`, stop and remove it > first with `docker rm -f codex-agent`. @@ -128,7 +156,8 @@ Codex CLI behaviour. > Network restrictions from `agent_config.json` are still enforced by the > entrypoint; customize `CODEX_CLI_COMMAND` only if you need additional Codex - > CLI overrides. + > CLI overrides. As with Option A, keep the mounted paths narrow so the agent + > only sees what it needs to modify. 2. Open a shell inside the container by referring to the name you just set: From ac51afc17afb5553ae7784d9e27e2fbde24a5760 Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 23:34:59 +0100 Subject: [PATCH 09/12] Document retrieving container ID by name --- docs/workflows/codex_cli_setup.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 280a8bd..3028efd 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -165,6 +165,13 @@ Codex CLI behaviour. docker exec -it codex-agent /bin/bash ``` + > **Need the full container ID for another command?** Run + > `docker container inspect --format '{{.Id}}' codex-agent` to print it + > directly without scanning the `docker ps` table. You can also embed that in + > another command — for example, + > `docker exec -it $(docker container inspect --format '{{.Id}}' codex-agent) /bin/bash` — + > but using the container name is usually simpler. + 3. Log in with your browser. Bind the login server to `0.0.0.0` (so Docker can forward traffic from your host) and pin the port to `1455` to match the publish rule above: From 472bcce3382bbb33f23c72857314022fe88a168f Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 23:35:04 +0100 Subject: [PATCH 10/12] Clarify codex login flags --- docs/workflows/codex_cli_setup.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index 3028efd..f385250 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -172,19 +172,20 @@ Codex CLI behaviour. > `docker exec -it $(docker container inspect --format '{{.Id}}' codex-agent) /bin/bash` — > but using the container name is usually simpler. -3. Log in with your browser. Bind the login server to `0.0.0.0` (so Docker can - forward traffic from your host) and pin the port to `1455` to match the - publish rule above: +3. Log in with your browser. The CLI already binds to all interfaces, so you + only need to pin the port to `1455` to match the publish rule above: ```bash - codex auth login --bind 0.0.0.0 --port 1455 + codex auth login --port 1455 ``` - You’ll see a short code and a URL. - Open the URL on your host machine, sign in to OpenAI, and paste the code. - Once confirmed, the CLI is authenticated. If the browser callback hangs, double-check that the container is still running and that port `1455` is - exposed on your `docker run` command. + exposed on your `docker run` command. Some CLI releases do not support + `--port`; in that case simply run `codex auth login` and use the port that + the CLI prints (publish the same port when you start Docker). 4. (Optional) To make login persist across runs, add this volume mount: From caad3ee02d18a163b9bcde8e2585414a187b604d Mon Sep 17 00:00:00 2001 From: Nikos Date: Wed, 24 Sep 2025 23:44:36 +0100 Subject: [PATCH 11/12] Clarify browser login port usage --- docs/workflows/codex_cli_setup.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index f385250..b6b116e 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -172,8 +172,10 @@ Codex CLI behaviour. > `docker exec -it $(docker container inspect --format '{{.Id}}' codex-agent) /bin/bash` — > but using the container name is usually simpler. -3. Log in with your browser. The CLI already binds to all interfaces, so you - only need to pin the port to `1455` to match the publish rule above: +3. Log in with your browser. The CLI listens on the container side of port + `1455`, so just make sure you publish the same port when you run Docker. + If your CLI version supports `--port`, pass it explicitly to avoid the + callback using a different value: ```bash codex auth login --port 1455 @@ -195,10 +197,14 @@ Codex CLI behaviour. 5. Start the Codex agent once login succeeds. Because you left `CODEX_CLI_COMMAND` empty when the container booted, launch the CLI manually - (the login flags are not needed anymore): + (the login flags are not needed anymore). The command below uses the + container name, and the second example shows how to resolve the full ID + automatically: ```bash docker exec -it codex-agent codex run + # or + docker exec -it $(docker container inspect --format '{{.Id}}' codex-agent) codex run ``` > Alternatively, stop the temporary container (`docker stop codex-agent && docker rm codex-agent`) and From 6cabe158e8615cf760abdb54d82f2dc43a273300 Mon Sep 17 00:00:00 2001 From: Nikos Date: Thu, 25 Sep 2025 00:00:36 +0100 Subject: [PATCH 12/12] Document OAuth callback troubleshooting --- docs/workflows/codex_cli_setup.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/workflows/codex_cli_setup.md b/docs/workflows/codex_cli_setup.md index b6b116e..3796b4a 100644 --- a/docs/workflows/codex_cli_setup.md +++ b/docs/workflows/codex_cli_setup.md @@ -175,7 +175,9 @@ Codex CLI behaviour. 3. Log in with your browser. The CLI listens on the container side of port `1455`, so just make sure you publish the same port when you run Docker. If your CLI version supports `--port`, pass it explicitly to avoid the - callback using a different value: + callback using a different value. The CLI prints `Starting local login + server on http://localhost:1455` when the listener is ready—if you do not + see that line, wait a second before opening the browser link: ```bash codex auth login --port 1455 @@ -184,10 +186,10 @@ Codex CLI behaviour. - You’ll see a short code and a URL. - Open the URL on your host machine, sign in to OpenAI, and paste the code. - Once confirmed, the CLI is authenticated. If the browser callback hangs, - double-check that the container is still running and that port `1455` is - exposed on your `docker run` command. Some CLI releases do not support - `--port`; in that case simply run `codex auth login` and use the port that - the CLI prints (publish the same port when you start Docker). + double-check that the container is still running (`docker ps`) and that + you see `0.0.0.0:1455->1455/tcp` in the output. Some CLI releases do not + support `--port`; in that case simply run `codex auth login` and use the + port that the CLI prints (publish the same port when you start Docker). 4. (Optional) To make login persist across runs, add this volume mount: @@ -217,6 +219,20 @@ Codex CLI behaviour. docker rm codex-agent ``` +> **OAuth callback troubleshooting** +> +> If the browser redirects to `http://localhost:1455/auth/callback` and then +> spins forever: +> +> 1. Run `docker ps` and confirm the container is still running **and** the +> port mapping `0.0.0.0:1455->1455/tcp` is present. +> 2. Run `docker logs codex-agent | tail` to make sure `codex auth login` +> printed “Starting local login server on http://localhost:1455”. If it +> never appeared, rerun the login command inside the container. +> 3. Another process on your host might already be bound to port 1455. Restart +> the container with a different port (for example `-p 8080:1455`) and pass +> the same port number to `--port` during `codex auth login`. + --- ## 5. Verify Codex CLI connectivity