Debugging

How to inspect the sandbox and debug

You might be wondering… if this is not a Docker container, how can you see what’s going on inside Docker!? How to debug/install things?

That’s quite straightforward.

You first need to run:

sbx ls

Note down the name of the sandbox for the agent you ran, e.g. ralph-claude-my-app-a1b2c3d4. Ralph also prints this name when it starts.

And then you can run bash into any of the sandboxes like so:

sbx exec -it <sandbox-name> bash # e.g. sbx exec -it ralph-claude-my-app-a1b2c3d4 bash

And you have full control over the sandbox, just like a regular container. You can install packages, run commands, etc.

You can also run the agent CLI inside the sandbox (make sure to navigate to the project directory first).

sbx exec -it <sandbox-name> bash
cd /path/to/your/project # this is the same path as the path in the root machine, e.g. /Users/your-username/Documents/your-project
claude # or codex, copilot, cursor, gemini, opencode

Re-running ./ralph.sh, ./ralph.sh --login, or ./ralph.sh --ports is safe at any point — Ralph probes sbx ls and emits sbx run --name ... <agent> . only when the sandbox doesn’t exist yet, and sbx run <sandbox-name> to reattach afterwards. The first form is create-only and would otherwise error with --name can only be used when creating a new sandbox. See RALPH.md for the full lifecycle.

Allowing network access

Docker Sandboxes block outbound HTTP/HTTPS by default (deny-by-default, or a “Balanced” allowlist depending on the policy you chose at install). If the agent can’t reach a host it needs — npm install fails, an API call is refused, package downloads hang — grant access with sbx policy. Changes take effect immediately and persist across sandbox restarts.

Use the sandbox name from sbx ls (or ./ralph.sh --print-name), e.g. ralph-claude-my-app-a1b2c3d4.

Allow a single domain for one sandbox:

sbx policy allow network <my-sandbox> api.example.com

Allow all outbound traffic for one sandbox (use sparingly — this opts that sandbox out of network filtering):

sbx policy allow network <my-sandbox> "**"

Allow several domains at once with a comma-separated list (handy when package installs are blocked):

sbx policy allow network <my-sandbox> "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"

Apply a rule to every sandbox on the machine with the global flag -g instead of a sandbox name:

sbx policy allow network -g api.example.com

Inspect and manage rules:

sbx policy ls                                  # list active rules
sbx policy log                                 # inspect connection history
sbx policy deny network <my-sandbox> ads.example.com   # block a host

Domain matching notes:

• example.com matches only the exact domain (any port); it does not match subdomains.
• *.example.com matches subdomains like api.example.com but not the root example.com — specify both to cover both.
• Append a port to scope the rule, e.g. example.com:443.
• If a domain matches both an allow and a deny rule, the deny rule wins.

See Docker’s Policies and Network policies docs for the full reference.

Authentication issues in Sandboxes / Login not persisting

Agentic CLIs might change their auth mechanism over time and Docker Sandboxes might fail persisting OAuth tokens (when you perform /login inside the sandbox shell).

Fortunately, Docker Sandboxes also forward env variables when you create a sandbox.

Here’s how to set up authentication using an API key:

1. Important 🚨: delete the sandbox that needs authentication. Env vars are only picked up when you create a new sandbox.

2. Go to Docker security credentials to find each env variables you need. For example, anthropic needs ANTHROPIC_API_KEY, OpenAI need OPENAI_API_KEY, Cursor needs CURSOR_API_KEY, etc.

3. Export the env variables in your shell. For example:

export ANTHROPIC_API_KEY=your-anthropic-api-key
export OPENAI_API_KEY=your-openai-api-key
export CURSOR_API_KEY=your-cursor-api-key

If you use bash, you can export the env variables in your .bashrc file, or if you use zsh, you can export the env variables in your .zshrc file.

4. Recreate the sandbox by running ./ralph.sh --login again.