›_ Codex Issues
Codex Issues / #37076

CLI documentation incorrectly states that `!` shell commands inherit sandbox settings

Open 💬 1 comment Opened Aug 5, 2026 by hanohrs

What is the type of issue?

Documentation is incorrect

What is the issue?

The Codex CLI documentation states that user-initiated ! shell commands run under the current approval and sandbox settings, but this does not match the observed behavior or the App Server documentation.

The CLI documentation currently says:

  • The --sandbox option selects the sandbox policy for “model-generated shell commands”.
  • The interactive-shortcuts section says: “Prefix a line with ! to run a local shell command under the current approval and sandbox settings.”

However, a command entered with ! is user-initiated rather than model-generated, and it appears to run outside the configured sandbox.

For example, with Codex CLI v0.146.0:

$ codex --sandbox read-only

Then, in the interactive session:

!touch foobar

The command succeeds and creates foobar, even though the session was started with --sandbox read-only.

This behavior is consistent with the App Server documentation for thread/shellCommand, which explicitly states that the API:

  • runs outside the sandbox with full access; and
  • does not inherit the thread sandbox policy.

There is also a conflicting statement in PR #14988. Its description says that thread/shellCommand commands are executed within the sandbox and that the implementation mirrors the existing TUI ! behavior. This appears inconsistent with both the current behavior of the merged implementation and the current App Server documentation.

Because this distinction affects the security expectations of CLI users, could the interactive-shortcuts documentation be corrected to state that ! commands run outside the sandbox with full access and do not inherit the current sandbox policy?

A clarification or correction on PR #14988 would also help prevent its description from being treated as documentation of the current security behavior.

Where did you find it?

  • CLI global flags (--sandbox):

https://learn.chatgpt.com/docs/developer-commands?surface=cli#cli-global-flags

  • CLI interactive shortcuts (!):

https://learn.chatgpt.com/docs/developer-commands?surface=cli#cli-interactive-shortcuts

  • App Server documentation (thread/shellCommand):

https://learn.chatgpt.com/docs/app-server#run-a-thread-shell-command

  • PR #14988

View original on GitHub ↗

1 Comment

Bishnuu72 · 2 days ago

Verified against current main — the documented behavior is incorrect, and the
unsandboxed execution is intentional per the implementation. Adding exact code
citations so maintainers don't need to re-trace it:

Execution path: TUI ! input → AppCommand::run_user_shell_command
(codex-rs/tui/src/chatwidget/input_submission.rs:45) → app-server
thread/shellCommand (codex-rs/tui/src/app_server_session.rs:1444) →
Op::RunUserShellCommand
(codex-rs/app-server/src/request_processors/thread_processor.rs) →
execute_user_shell_command (codex-rs/core/src/session/handlers.rs:103).

Sandbox handling (codex-rs/core/src/tasks/user_shell.rs):

  • Line 219: sandbox: SandboxType::None — the command never runs under the

configured sandbox policy.

  • Line 204: PermissionProfile::Disabled.
  • Lines 211–212: explicit comment — "/shell is the explicit full-access

escape hatch, so it must not inherit a managed proxy from the surrounding
session or turn."

So ! touch foobar succeeding under --sandbox read-only is by design, not a
sandbox leak. This also confirms that PR #14988's description ("executed within
the sandbox") does not match the merged implementation.

Scope note for whoever fixes this: the incorrect statement appears to exist
only on the external developer-commands docs page. Everything inside the repo
is already consistent with the actual behavior:

  • codex-rs/app-server/README.md documents thread/shellCommand as running

"unsandboxed with full access rather than inheriting the thread sandbox
policy".

  • codex --help for --sandbox says it selects "the sandbox policy to use when

executing model-generated shell commands"
(codex-rs/utils/cli/src/shared_options.rs).

  • The TUI's inline hint ("Prefix a command with ! to run it locally") makes no

sandbox claim.

So no in-repo change is needed — only the published docs page (and ideally a
note on PR #14988) require correction. Suggested replacement wording for the
interactive-shortcuts section: "Prefix a line with ! to run a local shell
command directly on your machine. User shell commands run outside the sandbox
with full access and do not use the session's approval or sandbox settings."