codex-safe-setup

Files (16)

• SKILL.md
• openai.yaml · agents/
• configuration-profiles.md · references/
• recovery.md · references/
• security-contract.md · references/
• Assess-CodexSafety.ps1 · scripts/
• Common.ps1 · scripts/
• Install-CodexSafety.ps1 · scripts/
• Install-Prerequisites.ps1 · scripts/
• New-CodexCheckpoint.ps1 · scripts/
• Remove-LegacyDesktopSelectorArtifacts.ps1 · scripts/
• Rollback-CodexSafety.ps1 · scripts/
• Test-CodexSafety.ps1 · scripts/
• Test-DesktopPermissionE2E.ps1 · scripts/
• TomlConfigEditor.ps1 · scripts/
• Upgrade-CodexSafety.ps1 · scripts/

SKILL.md (first lines)

# Codex Safe Setup

Treat approval as a workflow choice, not a security boundary. Limit what Codex can write, read, and send; preserve recovery; then distinguish configuration checks from runtime proof.

## Required safety contract

Read [references/security-contract.md](references/security-contract.md) before assessing or changing a machine. Read [references/configuration-profiles.md](references/configuration-profiles.md) before presenting choices. Read [references/recovery.md](references/recovery.md) before enabling checkpoints or discussing recovery.

Never claim the resulting machine is absolutely safe. Never use an anecdotal credential theft report as proof of causation. If a real credential may already have been exposed, advise rotation, revocation, and usage review; configuration changes cannot undo prior exposure.

Do not read secret contents during assessment. Inspect only configuration text, tool versions, and the existence of known sensitive locations. Redact values in all reports.

## Workflow

### 1. Assess without changing state

Select `pwsh` when available; otherwise use Windows PowerShell only for assessment and bootstrap work.

Run:

```powershell
& <skill-dir>/scripts/Assess-CodexSafety.ps1
```

Report the effective evidence, including Full Access or legacy/new profile state, approval policy and reviewer, filesystem and command-network boundaries, Windows sandbox implementation, prerequisite versions, configuration conflicts, and unverified external tool surfaces.

### Existing installations and plugin updates

Plugin bundle updates and applied machine configuration are separate state layers. Updating or reinstalling the plugin does not silently rewrite `config.toml`, rules, checkpoints, or an already-running task.

If `CODEX_HOME/safe-setup/install-state.json` exists, do not rerun the first-install path. Run `Upgrade-CodexSafety.ps1` without confirmation first. It must preserve the recorded approval, network, Windows sandbox, workspace, backup, and rollback choices; show the previous and requested values; and make no changes until the user confirms the upgrade. Security broadening still requires the same acknowledgement as a new install.

For a 0.1.1-or-earlier `Unrestricted` installation, explain that the old wildcard proxy representation did not provide native direct networking. The 0.1.2 migration disables the filtering proxy, removes the wildcard domain table, records state schema 2, and requires a full Codex restart plus a fresh task. Never claim the plugin update alone activated this migration.

For 0.1.4-or-earlier installations, version 0.1.5 records state schema 4 and removes the alternate normal-Git Status / Commit bridge. Upgrade rewrites any schema-2 workspace registry to the recovery-only Save/List schema and does not preserve commit authorizations.

For 0.1.5 installations, version 0.1.6 records state schema 5 and introduced the legacy DynamicUi route. That migration removed the plugin-owned permission profile and restored built-in UI switching, but it also removed Custom from the menu.

For 0.1.6 installations, version 0.1.7 records state schema 6 and restores the Custom menu through one permission-profile family. DynamicUi removes legacy `sandbox_mode` / `sandbox_workspace_write`, maps a deliberate legacy startup choice to the corresponding built-in `default_permissions` ID, and writes `codex-safe-workspace` with positive grants only. It requires Codex CLI 0.147.0 or newer. Never put an explicit filesystem `deny` in the DynamicUi Custom profile: Codex preserves deny entries across profile changes, which can make a later Full Access selection remain managed and restricted.

For 0.1.7 installations, version 0.1.8 records state schema 7 and removes the sole named DynamicUi profile plus `default_permissions`. The old Desktop selector temporarily displayed that sole name while a running turn stopped sending permission overrides, even though the user's last deliberate click still governed the next turn. DynamicUi now always writes a distinct `Custom (config.toml)` workspace-write fallback. This is an intentional backed-up migration; use `-MigrateLegacySettings` after explaining it. StrictProfile keeps the named profile.

For 0.1.8 or 0.1.9 development installations, version 0.2.0 records state schema 9. DynamicUi removes legacy sandbox and top-level approval keys, sets built-in `:workspace` only as the startup default, and installs two positive-only named profiles: `codex-safe-workspace` and `codex-safe-workspace-offline`. Runtime semantics remain last-manual-click wins. Do not claim this config shape alone fixes visible label oscillation on every Desktop build; the optional Windows compatibility layer below is a separate installation and state boundary.

### 2. Explain the choices before asking

Lead with: **Do not treat approval as safety. Limit what the agent can change, read, and send.**

Choose the permission-routing mode before approval or network settings:

- `DynamicUi` (default for 0.2.0): install two positive-only named profiles, `codex-safe-workspace` and `codex-safe-workspace-offline`, with top-level `default_permissions = ":workspace"`. Remove top-level `sandbox_mode`, `approval_policy`, `approvals_reviewer`, and `[sandbox_workspace_write]` so the dynamic route has one authoritative permission family and no sticky filesystem denies. Custom / 自定义, Full Access, Workspace, and Read-only must replace one another on the next user message without restarting Codex. Disclose that Custom follows the broader workspace sandbox read scope and cannot install credential deny-globs; workspace credential files remain readable while the workspace is writable. Require Codex CLI 0.138.0 or newer and `-AcknowledgeDynamicUiReadScope`. DynamicUi supports `Off` and `Unrestricted`; the offline profile always disables command network. It rejects `Allowlist` because a persistent proxy would keep constraining Full Access.
- `StrictProfile`: write `default_permissions = "codex-safe-workspace"` so the same named root-deny, minimal-read, credential-deny, and proxy-allowlist profile is the fixed default. Use it only when that fixed boundary matters more than same-task Full Access switching.

Offer these approval modes over the selected filesystem route:

- `BoundedAutonomy` (recommended): no approval prompts; attempts outside the boundary fail.
- `AskMe`: eligible boundary crossings go to the user.
- `AutoReview`: eligible boundary crossings go to a reviewer agent. Explain that this replaces the reviewer and does not strengthen the sandbox.

Offer command-network modes separately: `Off` (recommended) disables both command networking and the proxy; `Allowlist` enables the filtering proxy with explicit domains; `Unrestricted` disables the proxy and enables direct command networking for ordinary protocols such as SSH, only after a high-risk acknowledgement. Explain that command-network settings do not control Web Search, Browser, Computer Use, apps, plugins, MCP, or cloud tasks.

Before accepting `Unrestricted`, give the complete disclosure below in the user's language. Do not reduce it to "high risk" or ask for acknowledgement before explaining it:

- Enabling unrestricted command networking does not itself expand filesystem permissions or add deletion authority. The active filesystem profile still applies, and files that are already writable inside the workspace can still be changed or deleted.
- Disabling the filtering proxy removes the public-destination boundary and permits direct protocols such as SSH: any data a sandboxed command can already read or generate may be sent to any public Internet destination. That can include source, configuration, command output, private data, and credentials whose filenames were not covered by deny rules.
- Untrusted web pages, issues, or dependency documentation can contain prompt injection that induces exfiltration or unsafe commands. Networked commands can also download malware or vulnerable dependencies and introduce license-restricted content.
- This does not mean disclosure will automatically occur. It means a human, model, or prompt-injection mistake has a much larger possible consequence, and no domain rule is enforced in direct mode. Recommend `Allowlist` for normal proxy-compatible work and `Unrestricted` only when direct protocols are required or destinations cannot be enumerated.

Only after this disclosure, require an explicit acknowledgement equivalent to "I understand and accept unrestricted command-network risk."

### 3. Obtain dependency consent separately

Recommend PowerShell 7 on Windows because it reduces legacy shell, encoding, quoting, and compatibility surprises. State that it is not a security boundary and cannot prevent semantic path mistakes.

Recommend Codex CLI for version detection, `execpolicy` rule validation, and a complete verification result. StrictProfile can be configured without it but remains `PARTIALLY VERIFIED`; DynamicUi must refuse apply unless a detected CLI is version 0.138.0 or newer because its config.toml Custom catalog behavior is version-specific.

Never install either dependency without an explicit yes. After consent, run:

```powershell
& <skill-dir>/scripts/Install-Prerequisites.ps1 -PowerShell7 Install -CodexCli Install
```

Use `Skip` for each declined dependency. Do not silently install Node.js when npm is unavailable.

### 4. Preview the exact configuration

Choose Windows `Elevated` when the user accepts its administrator-approved setup; otherwise use `Unelevated` or `Keep` and explain the weaker boundary.

Run `Install-CodexSafety.ps1` with `-PlanOnly`. For StrictProfile, include `-MigrateLegacySettings` only after explaining that legacy sandbox keys will be replaced after backup. For DynamicUi, use it when replacing an older generic Custom or single-profile shape after explicit review; the resulting dual named-profile route is the intended DynamicUi representation.

Show the configuration path, managed keys, chosen boundaries, checkpoint registration, backup location, rollback command, and controls that remain outside this skill.

DynamicUi must write built-in `default_permissions = ":workspace"`, both plugin-owned positive-only named profiles, and no legacy sandbox or top-level approval keys. StrictProfile writes `default_permissions = "codex-safe-workspace"` with explicit root and credential denies and removes the DynamicUi compatibility profile. Never mix the two configuration families. Do not create or modify managed `allowed_permission_profiles` restrictions.

Plugin-owned top-level settings live inside the generated `codex-safe-setup top-level` block, placed strictly before the first `[table]`; named profiles live in the `codex-safe-setup profiles` block at the end of the file. If the plan reports `SCOPE WARNING` findings, a key that belongs to Codex's top level (for example `model`, `notify`, or `service_tier`) sits under a wrong `[table]` — usually because an unrelated table was inserted above it. Explain the finding; offer `-RepairForeignMisplacedKeys` only after confirmation, and relay any `SCOPE CONFLICT` lines verbatim: those keys already exist at the top level, so only the user may decide which value wins. The installer refuses to write any candidate that fails its structural validation, and every write is protected by a plan-time SHA-256 check (`CONCURRENT_MODIFICATION` means something else edited config.toml mid-flight; rerun the plan).

For a linked Git worktree, keep the parent repository's shared .git protected in the safe default. If the user temporarily selects Full Access for a task, use native Git normally in that task; Full Access must remove the sandbox restriction rather than route Git through a separate backend. Never add a parent-.git write exception or a commit bridge to compensate for a UI/runtime mismatch.

If direct Git reports surprising tracked deletions in the safe default, treat sandbox visibility or host ACL as hypotheses and verify them read-only. The codexsandboxonline and codexsandboxoffline account names identify Windows sandbox/network variants; neither name proves Full Access, filesystem scope, or effective task permissions.

### 5. Apply or upgrade only after confirmation

For an existing installation, apply the already previewed upgrade with:

```powershell
& <skill-dir>/scripts/Upgrade-CodexSafety.ps1 `
  -ConfirmUpgrade `
  -AcknowledgeDynamicUiReadScope `
  -AcknowledgeRisk `
  -AcknowledgeAdminSetup `
  -NonInteractive
```

Omit acknowledgements that do not apply to the selected route and network mode. DynamicUi always requires its read-scope acknowledgement. The upgrade writes a new transaction-scoped backup and immutable previous-state snapshot so rollback can traverse one configuration change at a time.

For a first installation, continue with the flow below.

After approval, rerun with `-ConfirmApply -NonInteractive`. DynamicUi also requires `-AcknowledgeDynamicUiReadScope`; `Unrestricted` requires `-AcknowledgeRisk`; `Elevated` requires `-AcknowledgeAdminSetup`.

From QianQIUlp/codex-safe-setup, Apache-2.0.

More from QianQIUlp/codex-safe-setup