c493ea1347
Updated all documentation and configuration files: Documentation changes: - Updated README.md to describe LLMX as LiteLLM-powered fork - Updated CLAUDE.md with LiteLLM integration details - Updated 50+ markdown files across docs/, llmx-rs/, llmx-cli/, sdk/ - Changed all references: codex → llmx, Codex → LLMX - Updated package references: @openai/codex → @llmx/llmx - Updated repository URLs: github.com/openai/codex → github.com/valknar/llmx Configuration changes: - Updated .github/dependabot.yaml - Updated .github workflow files - Updated cliff.toml (changelog configuration) - Updated Cargo.toml comments Key branding updates: - Project description: "coding agent from OpenAI" → "coding agent powered by LiteLLM" - Added attribution to original OpenAI Codex project - Documented LiteLLM integration benefits Files changed: 51 files (559 insertions, 559 deletions) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
96 lines
6.5 KiB
Markdown
96 lines
6.5 KiB
Markdown
## Sandbox & approvals
|
|
|
|
What LLMX is allowed to do is governed by a combination of **sandbox modes** (what LLMX is allowed to do without supervision) and **approval policies** (when you must confirm an action). This page explains the options, how they interact, and how the sandbox behaves on each platform.
|
|
|
|
### Approval policies
|
|
|
|
LLMX starts conservatively. Until you explicitly tell it a workspace is trusted, the CLI defaults to **read-only sandboxing** with the `read-only` approval preset. LLMX can inspect files and answer questions, but every edit or command requires approval.
|
|
|
|
When you mark a workspace as trusted (for example via the onboarding prompt or `/approvals` → “Trust this directory”), LLMX upgrades the default preset to **Auto**: sandboxed writes inside the workspace with `AskForApproval::OnRequest`. LLMX only interrupts you when it needs to leave the workspace or rerun something outside the sandbox.
|
|
|
|
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
|
|
|
|
- Every session starts in a sandbox. Until a repo is trusted, LLMX 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 LLMX 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:
|
|
- `llmx --sandbox read-only --ask-for-approval on-request`
|
|
- `llmx --sandbox workspace-write --ask-for-approval on-request`
|
|
|
|
### Can I run without ANY approvals?
|
|
|
|
Yes, you can disable all approval prompts with `--ask-for-approval never`. This option works with all `--sandbox` modes, so you still have full control over LLMX's level of autonomy. It will make its best attempt with whatever constraints you provide.
|
|
|
|
### Common sandbox + approvals combinations
|
|
|
|
| Intent | Flags | Effect |
|
|
| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | LLMX can read files and answer questions. LLMX 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` | LLMX can read files, make edits, and run commands in the workspace. LLMX requires approval for actions outside the workspace or for network access. |
|
|
| Auto (preset; trusted repos) | `--full-auto` (equivalent to `--sandbox workspace-write` + `--ask-for-approval on-request`) | LLMX 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`).
|
|
|
|
#### Fine-tuning in `config.toml`
|
|
|
|
```toml
|
|
# approval mode
|
|
approval_policy = "untrusted"
|
|
sandbox_mode = "read-only"
|
|
|
|
# full-auto mode
|
|
approval_policy = "on-request"
|
|
sandbox_mode = "workspace-write"
|
|
|
|
# Optional: allow network in workspace-write mode
|
|
[sandbox_workspace_write]
|
|
network_access = true
|
|
```
|
|
|
|
You can also save presets as **profiles**:
|
|
|
|
```toml
|
|
[profiles.full_auto]
|
|
approval_policy = "on-request"
|
|
sandbox_mode = "workspace-write"
|
|
|
|
[profiles.readonly_quiet]
|
|
approval_policy = "never"
|
|
sandbox_mode = "read-only"
|
|
```
|
|
|
|
### Sandbox mechanics by platform {#platform-sandboxing-details}
|
|
|
|
The mechanism LLMX uses to enforce the sandbox policy depends on your OS:
|
|
|
|
- **macOS 12+** uses **Apple Seatbelt**. LLMX invokes `sandbox-exec` with a profile that corresponds to the selected `--sandbox` mode, constraining filesystem and network access at the OS level.
|
|
- **Linux** combines **Landlock** and **seccomp** APIs to approximate the same guarantees. Kernel support is required; older kernels may not expose the necessary features.
|
|
- **Windows (experimental)**:
|
|
- Launches commands inside a restricted token derived from an AppContainer profile.
|
|
- Grants only specifically requested filesystem capabilities by attaching capability SIDs to that profile.
|
|
- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.
|
|
|
|
Windows sandbox support remains highly experimental. It cannot prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders).
|
|
|
|
In containerized Linux environments (for example Docker), sandboxing may not work when the host or container configuration does not expose Landlock/seccomp. In those cases, configure the container to provide the isolation you need and run LLMX with `--sandbox danger-full-access` (or the shorthand `--dangerously-bypass-approvals-and-sandbox`) inside that container.
|
|
|
|
### Experimenting with the LLMX Sandbox
|
|
|
|
To test how commands behave under LLMX's sandbox, use the CLI helpers:
|
|
|
|
```
|
|
# macOS
|
|
llmx sandbox macos [--full-auto] [COMMAND]...
|
|
|
|
# Linux
|
|
llmx sandbox linux [--full-auto] [COMMAND]...
|
|
|
|
# Legacy aliases
|
|
llmx debug seatbelt [--full-auto] [COMMAND]...
|
|
llmx debug landlock [--full-auto] [COMMAND]...
|
|
```
|