Codex Sandbox Permission Profiles: Allow npm Without Full Access
Keep Codex's workspace protections while allowing package-registry access. Configure a named permission profile, enable the network proxy, test allowed and blocked operations, and understand broad filesystem reads, native sandboxing, and enterprise profile restrictions.
Contents

If Codex edits your repository but cannot download npm packages, check its sandbox permission profile before changing API settings. The built-in :workspace profile disables command networking, so this affects developers running dependency installs inside local Codex sessions. Extend :workspace, enable the network proxy, and allow the registry hostname instead of switching to full access.
As of 2026-11-19, OpenAI documents permission profiles as beta. This guide configures local command execution and uses Bash examples for macOS, Linux, or WSL2.
What does the default workspace profile allow?
With a Git repository as the workspace root, :workspace lets sandboxed commands edit source files while protecting selected directories. Under each workspace root, .git, .codex, .agents, and .aws remain read-only. That prevents direct writes to repository configuration such as .codex/config.toml and hooks under .git/hooks. These protections apply to paths under the workspace roots, not every similarly named directory on the machine.
Reads are broader. Commands can read outside the repository when your operating-system permissions permit it. OpenAI’s explanation of the default sandbox boundaries describes why this supports compilers, SDKs, libraries, and configuration stored elsewhere. It does not make those files confidential from Codex commands.
Networking is disabled because a command that can read data should not automatically be able to upload it. Dependency downloads need additional access for the same reason. OpenAI also documents that child processes inherit their parent’s sandbox constraints, including descendants that outlive the original command.
For an occasional download, review the network-access request rather than changing your default profile. Codex can send such requests to you or to automatic review, as described in its network proxy explanation. For repeated dependency downloads, use a registry-specific profile; keep networking disabled for workflows that do not need it.
Configure a dev profile for the npm registry
Use an installed Codex CLI that supports the documented codex sandbox --permission-profile interface. The checks below also need npm, curl, and Bash. Start from the root of a disposable Git checkout while validating the policy.
Edit your personal ~/.codex/config.toml. Merge the following settings into existing tables rather than adding duplicate table definitions. This sets dev as your default permission profile.
Do not combine this configuration with legacy sandbox_mode or [sandbox_workspace_write] settings. The permission-profile documentation requires choosing one configuration system rather than mixing them.
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" preserves the built-in protections, including the read-only .git and .codex paths. The additional filesystem entries make editor and development-container settings read-only. They deny access to the listed environment files and the secrets subtree under each workspace root. OpenAI defines the filesystem permission values as read for read-only access, write for reading and writing, and deny for blocking access.
The network configuration has two separate switches. permissions.dev.network.enabled = true permits networking; network_proxy = true enables enforcement of domain rules. As the network permissions documentation explains, enabling networking without an active proxy grants direct network access. The domain rules are not enforced in that case. Do not omit the proxy setting.
OpenAI’s enterprise security cookbook includes registry.npmjs.org in its dependency-access example. Here, example.com is an explicitly denied destination used for a verification check. Under the documented domain-rule behavior, explicit deny rules override matching allow rules; other destinations require approval or are blocked.
This configuration does not grant unrestricted access to every host a package installation might contact. Add another hostname only after identifying why your project needs it.
Verify both the permission and the restriction
Use codex sandbox to test commands directly under the profile. Include --include-managed-config so profile resolution also includes managed requirements. That matters when an enterprise policy restricts your choices.
First, check the registry from Bash:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
A successful npm ping reports PONG. The cache option places npm’s cache inside the workspace here, avoiding a separate write grant for a cache elsewhere. This proves registry connectivity, not that every dependency or installation script can complete.
Next, check workspace writes, protected Git metadata, and the denied domain. Run these separately. The Git check assumes .git is an existing directory, rather than a worktree pointer file.
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
The expected pattern is an allowed workspace write, a denied .git write, and a rejected network request. A configuration error, missing directory, or unrelated connection failure is not evidence that the intended restriction worked. If either restricted operation succeeds, stop and inspect the effective configuration before using the profile for normal work. These are verification checks to run, not reported test results.
After the checks pass, start a new Codex session from the repository root. Run /permissions and check the dev entry and its description, which OpenAI documents in its profile configuration example. With that profile active, retry your original dependency-install task. Keep its cache inside the workspace, or grant write access only to the specific external cache directory it needs.
What should you check when downloads still fail?
If the profile is not taking effect, first inspect the loaded configuration for legacy sandbox settings. Then check configuration precedence: command-line overrides or trusted project configuration can change what your personal defaults select. Do not keep adding permissions to a profile the session is not using.
If npm ping works but installation fails, inspect the failing destination and filesystem path separately. A request to another hostname needs its own network decision. A cache write outside the workspace needs a suitable filesystem rule. The filesystem and network permissions are separate: opening the network does not grant filesystem writes.
If an allowed destination still fails, check whether the client honors proxy settings. OpenAI’s network proxy implementation notes explain that some programs do not honor the proxy environment variables. Diagnose that client or its configuration rather than removing the sandbox boundary.
A failure connecting Codex to its model provider is a different problem from a sandboxed package-manager command being blocked. For provider authentication, Base URL, or protocol configuration, use the separate Codex API connection guide.
Does broad reading expose API keys?
Yes. Read-only protection prevents modification, not reading. OpenAI states the tradeoff directly in Inside the Codex sandbox:
The tradeoff is that sensitive files elsewhere on the machine may also remain readable (such as config files containing API keys).
The default profile therefore does not promise that secrets outside your repository are hidden.
The example denies only the specific root-relative .env and .env.local paths and the secrets subtree. It does not claim to cover every credential filename or location. Add appropriate deny rules for sensitive paths in your environment, including paths outside the workspace where necessary. Test with harmless fixtures rather than printing real credentials.
Writable files also remain a risk. OpenAI describes how modifying an installed package such as node_modules/prettier could affect a formatter your editor later runs outside the sandbox. Because node_modules is often ignored, that modification might not appear in git status. Review writable tools and generated dependencies as well as tracked source changes.
Teams using multiple coding agents should also review their Claude Code permissions for secrets and Git. Apply each tool’s own configuration rather than copying Codex permission keys into another client.
Why use native sandboxing instead of Docker?
Native sandboxing lets Codex use your existing development tools while applying operating-system restrictions to the commands it launches. OpenAI explains its native sandbox design as an alternative to requiring users to reproduce their development environment inside a container.
The practical example is iOS development on a Mac. A Docker container cannot run the native Mac toolchain or launch the iPhone simulator in the workflow OpenAI describes. Delegating those operations to the Mac host moves them outside the container’s sandbox, so the host operations still need their own restrictions.
On macOS, Codex uses Seatbelt. For Linux and WSL2, OpenAI’s sandbox setup instructions recommend installing bubblewrap through the distribution’s package manager. Treat a sandbox-startup failure separately from a denied registry request.
Native Windows needs its own validation. The Windows sandbox documentation recommends MXC on compatible devices and warns that the legacy unelevated implementation does not support denied read paths. Passing the Bash checks in WSL2 is not a substitute for testing native Windows enforcement.
A container remains an option when your entire workflow belongs inside it. For a host-dependent toolchain, identify and constrain the host operations instead of assuming a container also covers delegated work.
Can an enterprise prevent you from selecting dev?
Yes. Administrators can use managed requirements.toml to constrain which profiles users may select. A local profile definition does not override that restriction. OpenAI’s managed-requirements example shows this administrator policy:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
When allowed_permission_profiles is present, the final merged table is a complete allowlist. Profiles omitted from that table are denied, as are profiles explicitly set to false. If the example is the final managed allowlist, your custom dev profile is unavailable because it is not allowed. Ask the administrator to approve an appropriate build profile rather than trying to bypass the policy.
The managed-configuration documentation sets an important version boundary: permission-profile allowlists require Codex 0.138.0 or later. Codex 0.137.0 and earlier ignore allowed_permission_profiles and managed default_permissions. Check every managed client before relying on this control.
For rollout, verify an allowed build and a deliberately blocked action on each supported operating system. Keep the registry permissions narrow, confirm the expected profile is selected, and retain the negative checks when updating clients.