docs: align sandbox defaults, dedupe sections and improve getting started guide (#5357)
Tightened the docs so the sandbox guide matches reality, noted the new tools.view_image toggle next to web search, and linked the README to the getting-started guide which now owns the familiar tips (backtrack, --cd, --add-dir, etc.).
This commit is contained in:
Thibault Sottiaux
committed by
GitHub
GitHub
parent
3ed728790b
commit
2d9ee9dbe9
@@ -13,6 +13,11 @@ codex
|
||||
|
||||
You can also install via Homebrew (`brew install codex`) or download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).
|
||||
|
||||
## Documentation quickstart
|
||||
|
||||
- First run with Codex? Follow the walkthrough in [`docs/getting-started.md`](../docs/getting-started.md) for prompts, keyboard shortcuts, and session management.
|
||||
- Already shipping with Codex and want deeper control? Jump to [`docs/advanced.md`](../docs/advanced.md) and the configuration reference at [`docs/config.md`](../docs/config.md).
|
||||
|
||||
## What's new in the Rust CLI
|
||||
|
||||
The Rust implementation is now the maintained Codex CLI and serves as the default experience. It includes a number of features that the legacy TypeScript CLI never supported.
|
||||
@@ -47,40 +52,6 @@ You can enable notifications by configuring a script that is run whenever the ag
|
||||
|
||||
To run Codex non-interactively, run `codex exec PROMPT` (you can also pass the prompt via `stdin`) and Codex will work on your task until it decides that it is done and exits. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
|
||||
|
||||
### Use `@` for file search
|
||||
|
||||
Typing `@` triggers a fuzzy-filename search over the workspace root. Use up/down to select among the results and Tab or Enter to replace the `@` with the selected path. You can use Esc to cancel the search.
|
||||
|
||||
### Esc–Esc to edit a previous message
|
||||
|
||||
When the chat composer is empty, press Esc to prime “backtrack” mode. Press Esc again to open a transcript preview highlighting the last user message; press Esc repeatedly to step to older user messages. Press Enter to confirm and Codex will fork the conversation from that point, trim the visible transcript accordingly, and pre‑fill the composer with the selected user message so you can edit and resubmit it.
|
||||
|
||||
In the transcript preview, the footer shows an `Esc edit prev` hint while editing is active.
|
||||
|
||||
### `--cd`/`-C` flag
|
||||
|
||||
Sometimes it is not convenient to `cd` to the directory you want Codex to use as the "working root" before running Codex. Fortunately, `codex` supports a `--cd` option so you can specify whatever folder you want. You can confirm that Codex is honoring `--cd` by double-checking the **workdir** it reports in the TUI at the start of a new session.
|
||||
|
||||
### `--add-dir` flag
|
||||
|
||||
Need to work across multiple projects? Pass `--add-dir` one or more times to expose extra directories as writable roots for the current session while keeping the main working directory unchanged. For example:
|
||||
|
||||
```shell
|
||||
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared
|
||||
```
|
||||
|
||||
Codex can now inspect and edit files in each listed directory without leaving the primary workspace.
|
||||
|
||||
### Shell completions
|
||||
|
||||
Generate shell completion scripts via:
|
||||
|
||||
```shell
|
||||
codex completion bash
|
||||
codex completion zsh
|
||||
codex completion fish
|
||||
```
|
||||
|
||||
### Experimenting with the Codex Sandbox
|
||||
|
||||
To test to see what happens when a command is run under the sandbox provided by Codex, we provide the following subcommands in Codex CLI:
|
||||
|
||||
@@ -4,7 +4,7 @@ This crate implements the business logic for Codex. It is designed to be used by
|
||||
|
||||
## Dependencies
|
||||
|
||||
Note that `codex-core` makes some assumptions about certain helper utilities being available in the environment. Currently, this
|
||||
Note that `codex-core` makes some assumptions about certain helper utilities being available in the environment. Currently, this support matrix is:
|
||||
|
||||
### macOS
|
||||
|
||||
|
||||
@@ -310,6 +310,18 @@ This is reasonable to use if Codex is running in an environment that provides it
|
||||
|
||||
Though using this option may also be necessary if you try to use Codex in environments where its native sandboxing mechanisms are unsupported, such as older Linux kernels or on Windows.
|
||||
|
||||
### tools.\*
|
||||
|
||||
Use the optional `[tools]` table to toggle built-in tools that the agent may call. Both keys default to `false` (tools stay disabled) unless you opt in:
|
||||
|
||||
```toml
|
||||
[tools]
|
||||
web_search = true # allow Codex to issue first-party web searches without prompting you
|
||||
view_image = true # let Codex attach local images (paths in your workspace) to the model request
|
||||
```
|
||||
|
||||
`web_search` is also recognized under the legacy name `web_search_request`. The `view_image` toggle is useful when you want to include screenshots or diagrams from your repo without pasting them manually. Codex still respects sandboxing: it can only attach files inside the workspace roots you allow.
|
||||
|
||||
### approval_presets
|
||||
|
||||
Codex provides three main Approval Presets:
|
||||
@@ -873,3 +885,4 @@ notifications = [ "agent-turn-complete", "approval-requested" ]
|
||||
| `experimental_use_exec_command_tool` | boolean | Use experimental exec command tool. |
|
||||
| `projects.<path>.trust_level` | string | Mark project/worktree as trusted (only `"trusted"` is recognized). |
|
||||
| `tools.web_search` | boolean | Enable web search tool (alias: `web_search_request`) (default: false). |
|
||||
| `tools.view_image` | boolean | Enable the `view_image` tool so Codex can attach local image files from the workspace (default: false). |
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
## Getting started
|
||||
|
||||
Looking for something specific? Jump ahead:
|
||||
|
||||
- [Tips & shortcuts](#tips--shortcuts) – hotkeys, resume flow, prompts
|
||||
- [Non-interactive runs](./exec.md) – automate with `codex exec`
|
||||
- Ready for deeper customization? Head to [`advanced.md`](./advanced.md)
|
||||
|
||||
### CLI usage
|
||||
|
||||
| Command | Purpose | Example |
|
||||
@@ -77,21 +83,26 @@ For more information on how to use AGENTS.md, see the [official AGENTS.md docume
|
||||
|
||||
Typing `@` triggers a fuzzy-filename search over the workspace root. Use up/down to select among the results and Tab or Enter to replace the `@` with the selected path. You can use Esc to cancel the search.
|
||||
|
||||
#### Image input
|
||||
|
||||
Paste images directly into the composer (Ctrl+V / Cmd+V) to attach them to your prompt. You can also attach files via the CLI using `-i/--image` (comma‑separated):
|
||||
|
||||
```bash
|
||||
codex -i screenshot.png "Explain this error"
|
||||
codex --image img1.png,img2.jpg "Summarize these diagrams"
|
||||
```
|
||||
|
||||
#### Esc–Esc to edit a previous message
|
||||
|
||||
When the chat composer is empty, press Esc to prime “backtrack” mode. Press Esc again to open a transcript preview highlighting the last user message; press Esc repeatedly to step to older user messages. Press Enter to confirm and Codex will fork the conversation from that point, trim the visible transcript accordingly, and pre‑fill the composer with the selected user message so you can edit and resubmit it.
|
||||
|
||||
In the transcript preview, the footer shows an `Esc edit prev` hint while editing is active.
|
||||
|
||||
#### `--cd`/`-C` flag
|
||||
|
||||
Sometimes it is not convenient to `cd` to the directory you want Codex to use as the "working root" before running Codex. Fortunately, `codex` supports a `--cd` option so you can specify whatever folder you want. You can confirm that Codex is honoring `--cd` by double-checking the **workdir** it reports in the TUI at the start of a new session.
|
||||
|
||||
#### `--add-dir` flag
|
||||
|
||||
Need to work across multiple projects in one run? Pass `--add-dir` one or more times to expose extra directories as writable roots for the current session while keeping the main working directory unchanged. For example:
|
||||
|
||||
```shell
|
||||
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared
|
||||
```
|
||||
|
||||
Codex can then inspect and edit files in each listed directory without leaving the primary workspace.
|
||||
|
||||
#### Shell completions
|
||||
|
||||
Generate shell completion scripts via:
|
||||
@@ -102,6 +113,11 @@ codex completion zsh
|
||||
codex completion fish
|
||||
```
|
||||
|
||||
#### `--cd`/`-C` flag
|
||||
#### Image input
|
||||
|
||||
Sometimes it is not convenient to `cd` to the directory you want Codex to use as the "working root" before running Codex. Fortunately, `codex` supports a `--cd` option so you can specify whatever folder you want. You can confirm that Codex is honoring `--cd` by double-checking the **workdir** it reports in the TUI at the start of a new session.
|
||||
Paste images directly into the composer (Ctrl+V / Cmd+V) to attach them to your prompt. You can also attach files via the CLI using `-i/--image` (comma‑separated):
|
||||
|
||||
```bash
|
||||
codex -i screenshot.png "Explain this error"
|
||||
codex --image img1.png,img2.jpg "Summarize these diagrams"
|
||||
```
|
||||
|
||||
@@ -4,22 +4,20 @@ What Codex is allowed to do is governed by a combination of **sandbox modes** (w
|
||||
|
||||
### Approval policies
|
||||
|
||||
We've chosen a powerful default for how Codex works on your computer: `Auto`. Under this approval policy, Codex can read files, make edits, and run commands in the working directory automatically. However, Codex will need your approval to work outside the working directory or access network.
|
||||
Codex starts conservatively. Until you explicitly tell it a workspace is trusted, the CLI defaults to **read-only sandboxing** with the `read-only` approval preset. Codex can inspect files and answer questions, but every edit or command requires approval.
|
||||
|
||||
When you just want to chat, or if you want to plan before diving in, you can switch to `Read Only` mode with the `/approvals` command.
|
||||
When you mark a workspace as trusted (for example via the onboarding prompt or `/approvals` → “Trust this directory”), Codex upgrades the default preset to **Auto**: sandboxed writes inside the workspace with `AskForApproval::OnRequest`. Codex only interrupts you when it needs to leave the workspace or rerun something outside the sandbox.
|
||||
|
||||
If you need Codex to read files, make edits, and run commands with network access, without approval, you can use `Full Access`. Exercise caution before doing so.
|
||||
If you want maximum guardrails for a trusted repo, switch back to Read Only from the `/approvals` picker. If you truly need hands-off automation, use `Full Access`—but be deliberate, because that skips both the sandbox and approvals.
|
||||
|
||||
#### Defaults and recommendations
|
||||
|
||||
- Codex runs in a sandbox by default with strong guardrails: it prevents editing files outside the workspace and blocks network access unless enabled.
|
||||
- On launch, Codex detects whether the folder is version-controlled and recommends:
|
||||
- Version-controlled folders: `Auto` (workspace write + on-request approvals)
|
||||
- Non-version-controlled folders: `Read Only`
|
||||
- The workspace includes the current directory and temporary directories like `/tmp`. Use the `/status` command to see which directories are in the workspace.
|
||||
- You can set these explicitly:
|
||||
- `codex --sandbox workspace-write --ask-for-approval on-request`
|
||||
- Every session starts in a sandbox. Until a repo is trusted, Codex enforces read-only access and will prompt before any write or command.
|
||||
- Marking a repo as trusted switches the default preset to Auto (`workspace-write` + `ask-for-approval on-request`) so Codex can keep iterating locally without nagging you.
|
||||
- The workspace always includes the current directory plus temporary directories like `/tmp`. Use `/status` to confirm the exact writable roots.
|
||||
- You can override the defaults from the command line at any time:
|
||||
- `codex --sandbox read-only --ask-for-approval on-request`
|
||||
- `codex --sandbox workspace-write --ask-for-approval on-request`
|
||||
|
||||
### Can I run without ANY approvals?
|
||||
|
||||
@@ -32,7 +30,7 @@ Yes, you can disable all approval prompts with `--ask-for-approval never`. This
|
||||
| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |
|
||||
| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Reads only; never escalates |
|
||||
| Let it edit the repo, ask if risky | `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval for actions outside the workspace or for network access. |
|
||||
| Auto (preset) | `--full-auto` (equivalent to `--sandbox workspace-write` + `--ask-for-approval on-failure`) | Codex can read files, make edits, and run commands in the workspace. Codex requires approval when a sandboxed command fails or needs escalation. |
|
||||
| Auto (preset; trusted repos) | `--full-auto` (equivalent to `--sandbox workspace-write` + `--ask-for-approval on-request`) | Codex runs sandboxed commands that can write inside the workspace without prompting. Escalates only when it must leave the sandbox. |
|
||||
| YOLO (not recommended) | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | No sandbox; no prompts |
|
||||
|
||||
> Note: In `workspace-write`, network is disabled by default unless enabled in config (`[sandbox_workspace_write].network_access = true`).
|
||||
|
||||
Reference in New Issue
Block a user