From 2e82a1c0829c12b9acd15e35b920285cc301cb9a Mon Sep 17 00:00:00 2001 From: octane0411 Date: Sun, 8 Mar 2026 17:14:50 +0800 Subject: [PATCH 1/2] Clarify workflow auth and network requirements --- README.md | 13 +++++++++++++ docs/DEV_GUIDE.md | 38 ++++++++++++++++++++++++++++++++++++-- docs/WORKFLOW.template.md | 21 +++++++++++++++++++-- 3 files changed, 68 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index eea83933..87c58aa3 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,19 @@ as `WORKFLOW.md`, then change these fields before starting Symphony: If you want the dashboard, keep `server.port` in the workflow or pass `--port` on the CLI. +If your agent workflow needs authenticated networked CLIs such as `gh`, do not assume an +interactive login state or OS keychain entry will be available inside the agent turn. Export the +required credentials as environment variables before launching Symphony, for example: + +```bash +export LINEAR_API_KEY=lin_api_xxx +export GH_TOKEN="$(gh auth token)" +``` + +If your agent must push branches, open PRs, or call external APIs during a turn, also configure a +turn sandbox policy that explicitly allows network access instead of relying on a minimal +`workspaceWrite` sandbox object. + For a complete reference covering every supported field with defaults and inline documentation, see [docs/WORKFLOW.template.md](docs/WORKFLOW.template.md). diff --git a/docs/DEV_GUIDE.md b/docs/DEV_GUIDE.md index df92ea0b..1173b437 100644 --- a/docs/DEV_GUIDE.md +++ b/docs/DEV_GUIDE.md @@ -186,7 +186,7 @@ issue to "In Review" and leave a comment summarizing what you did. | `agent.max_retry_backoff_ms` | Max retry back-off delay in ms (exponential cap) | `300000` | | `agent.max_concurrent_agents_by_state` | Per-state concurrency overrides (map of state → limit) | `{}` | | `codex.command` | Shell command to launch Codex | `codex app-server` | -| `codex.approval_policy` | Codex approval policy: `never` / `on-failure` / `always` | Inherits Codex default | +| `codex.approval_policy` | Codex approval policy, passed through to the installed Codex schema | Inherits Codex default | | `codex.thread_sandbox` | Thread-level sandbox mode (e.g. `workspace-write`) | `null` | | `codex.turn_sandbox_policy` | Per-turn sandbox policy object | `null` | | `codex.turn_timeout_ms` | Max wall-clock time in ms for a full agent turn | `3600000` | @@ -215,6 +215,40 @@ node dist/src/cli/main.js --acknowledge-high-trust-preview --port 3000 > `--acknowledge-high-trust-preview` is a required safety flag. Symphony runs agent code without sandboxing by default; this flag confirms you understand that. +### Authenticated CLI note + +Environment variables from the launching shell are available to the agent runtime, but do not +assume that an interactive login state or OS keychain-backed credential will be usable inside an +agent turn. If your workflow depends on authenticated networked tools such as `gh`, export +env-based credentials before launching Symphony, for example: + +```bash +export LINEAR_API_KEY=lin_api_xxx +export GH_TOKEN="$(gh auth token)" +``` + +If the agent must use those tools during a turn, configure an explicit +`codex.turn_sandbox_policy` that allows network access, for example: + +```yaml +codex: + approval_policy: never + thread_sandbox: workspace-write + turn_sandbox_policy: + type: workspaceWrite + writableRoots: + - /tmp/symphony_workspaces + readOnlyAccess: + type: fullAccess + networkAccess: true + excludeTmpdirEnvVar: false + excludeSlashTmp: false +``` + +The exact accepted values depend on the installed Codex app-server version. To inspect the local +schema, run `codex app-server generate-json-schema --out ` and inspect the generated +`ThreadStartParams` and `TurnStartParams` schema files. + ### Step 6: Trigger a Test Issue in Linear 1. Open your Linear test project @@ -325,4 +359,4 @@ These fields take effect on the next poll tick without restarting Symphony: - Structured JSON logs are the primary observability surface - Launch with `--port 3000` to access the HTTP dashboard at `http://localhost:3000` ---- \ No newline at end of file +--- diff --git a/docs/WORKFLOW.template.md b/docs/WORKFLOW.template.md index 759c2d68..94c712f5 100644 --- a/docs/WORKFLOW.template.md +++ b/docs/WORKFLOW.template.md @@ -99,7 +99,8 @@ codex: command: codex app-server # Codex approval policy, passed through to the app-server. - # Common values: "never" | "on-failure" | "always" + # Common values depend on the installed Codex schema. + # Example values: never, on-request, on-failure # Default: (not set — inherits Codex default) approval_policy: never @@ -111,7 +112,14 @@ codex: # Per-turn sandbox policy passed through to Codex. # Example: # turn_sandbox_policy: - # type: workspace-write + # type: workspaceWrite + # writableRoots: + # - /tmp/symphony_workspaces + # readOnlyAccess: + # type: fullAccess + # networkAccess: true + # excludeTmpdirEnvVar: false + # excludeSlashTmp: false # Default: (not set) turn_sandbox_policy: null @@ -149,6 +157,15 @@ Rules: 3. Run the test suite before finishing. 4. Do not add secrets or credentials to the repository. +If this workflow needs authenticated external CLIs or APIs: + +1. Export the required credentials in the shell before launching Symphony. +2. Prefer env-based credentials such as `GH_TOKEN`, `GITHUB_TOKEN`, or provider-specific API keys. +3. Do not assume an interactive login state or OS keychain entry will be available inside the + agent turn. +4. If the agent must call networked tools during a turn, configure `codex.turn_sandbox_policy` + with explicit `networkAccess: true`. + When finished: 1. Update the Linear issue state to "Done" using the `linear_graphql` tool. From 9967453c4015b59ad095531cef147d19822692e0 Mon Sep 17 00:00:00 2001 From: octane0411 Date: Sun, 8 Mar 2026 17:29:20 +0800 Subject: [PATCH 2/2] Refine workflow env inheritance guidance --- README.md | 14 ++++++++------ docs/DEV_GUIDE.md | 27 +++++++++++++++------------ docs/WORKFLOW.template.md | 19 ++++++++++++------- 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 87c58aa3..135288ae 100644 --- a/README.md +++ b/README.md @@ -104,19 +104,21 @@ as `WORKFLOW.md`, then change these fields before starting Symphony: If you want the dashboard, keep `server.port` in the workflow or pass `--port` on the CLI. -If your agent workflow needs authenticated networked CLIs such as `gh`, do not assume an -interactive login state or OS keychain entry will be available inside the agent turn. Export the -required credentials as environment variables before launching Symphony, for example: +If your agent workflow needs access to environment variables from the launching shell, configure +Codex to inherit them in `codex.command`, for example: -```bash -export LINEAR_API_KEY=lin_api_xxx -export GH_TOKEN="$(gh auth token)" +```yaml +codex: + command: codex --config shell_environment_policy.inherit=all app-server ``` If your agent must push branches, open PRs, or call external APIs during a turn, also configure a turn sandbox policy that explicitly allows network access instead of relying on a minimal `workspaceWrite` sandbox object. +If a specific external CLI still does not see the credentials it needs in your environment, provide +that tool's credential via environment variables before launching Symphony. + For a complete reference covering every supported field with defaults and inline documentation, see [docs/WORKFLOW.template.md](docs/WORKFLOW.template.md). diff --git a/docs/DEV_GUIDE.md b/docs/DEV_GUIDE.md index 1173b437..9aa18b73 100644 --- a/docs/DEV_GUIDE.md +++ b/docs/DEV_GUIDE.md @@ -215,19 +215,17 @@ node dist/src/cli/main.js --acknowledge-high-trust-preview --port 3000 > `--acknowledge-high-trust-preview` is a required safety flag. Symphony runs agent code without sandboxing by default; this flag confirms you understand that. -### Authenticated CLI note +### Environment and networked CLI note -Environment variables from the launching shell are available to the agent runtime, but do not -assume that an interactive login state or OS keychain-backed credential will be usable inside an -agent turn. If your workflow depends on authenticated networked tools such as `gh`, export -env-based credentials before launching Symphony, for example: +If your workflow depends on environment variables from the launching shell, launch Codex with +shell environment inheritance enabled: -```bash -export LINEAR_API_KEY=lin_api_xxx -export GH_TOKEN="$(gh auth token)" +```yaml +codex: + command: codex --config shell_environment_policy.inherit=all app-server ``` -If the agent must use those tools during a turn, configure an explicit +If the agent must use networked tools during a turn, configure an explicit `codex.turn_sandbox_policy` that allows network access, for example: ```yaml @@ -245,9 +243,14 @@ codex: excludeSlashTmp: false ``` -The exact accepted values depend on the installed Codex app-server version. To inspect the local -schema, run `codex app-server generate-json-schema --out ` and inspect the generated -`ThreadStartParams` and `TurnStartParams` schema files. +With that in place, env-based credentials exported before launching Symphony are available to turn +commands. If a specific external CLI still does not find usable credentials in your environment, +provide that tool's credential explicitly via an env var such as `GH_TOKEN`, `GITHUB_TOKEN`, or a +provider-specific API key. + +The exact accepted sandbox and approval values depend on the installed Codex app-server version. To +inspect the local schema, run `codex app-server generate-json-schema --out ` and inspect the +generated `ThreadStartParams` and `TurnStartParams` schema files. ### Step 6: Trigger a Test Issue in Linear diff --git a/docs/WORKFLOW.template.md b/docs/WORKFLOW.template.md index 94c712f5..28258952 100644 --- a/docs/WORKFLOW.template.md +++ b/docs/WORKFLOW.template.md @@ -95,6 +95,8 @@ agent: # ============================================================ codex: # Shell command used to launch the Codex app-server. + # Add `--config shell_environment_policy.inherit=all` if agent turns + # should inherit environment variables from the launching shell. # Default: codex app-server command: codex app-server @@ -157,14 +159,17 @@ Rules: 3. Run the test suite before finishing. 4. Do not add secrets or credentials to the repository. -If this workflow needs authenticated external CLIs or APIs: +If this workflow needs environment variables from the launching shell: -1. Export the required credentials in the shell before launching Symphony. -2. Prefer env-based credentials such as `GH_TOKEN`, `GITHUB_TOKEN`, or provider-specific API keys. -3. Do not assume an interactive login state or OS keychain entry will be available inside the - agent turn. -4. If the agent must call networked tools during a turn, configure `codex.turn_sandbox_policy` - with explicit `networkAccess: true`. +1. Launch Codex with `--config shell_environment_policy.inherit=all`. +2. Export the required environment variables before launching Symphony. + +If the agent must call networked tools during a turn: + +1. Configure `codex.turn_sandbox_policy` with explicit `networkAccess: true`. +2. If a specific CLI still does not find usable credentials in your environment, provide that + tool's credential via an env var such as `GH_TOKEN`, `GITHUB_TOKEN`, or a provider-specific API + key. When finished: