How to use the sandbox browser image ?

[heady iris]

"agents": {
"defaults": {
"models": {
"deepseek/deepseek-v4-flash": {
"alias": "DeepSeek"
}
},
"model": {
"primary": "deepseek/deepseek-v4-flash"
},
"sandbox": {
"mode": "non-main",
"scope": "session",
"workspaceAccess": "rw",
"docker": {
"image": "openclaw-sandbox-common:bookworm-slim",
"network": "bridge",
"dangerouslyAllowExternalBindSources": true,
},
"browser": {
"enabled": true,
"image": "openclaw-sandbox-browser:bookworm-slim",
"autoStart": true,
"autoStartTimeoutMs": 12000,
"allowHostControl": true,
}
}
}
},

According to https://docs.openclaw.ai/gateway/sandboxing#images-and-setup, I have already built the sandbox browser image. But I don't know how to use the sandbox browser, I hope someone experienced can help me.

[brazen hemlock]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[wicked heart]

Yep — the important bit is: you usually don’t “use” the browser image directly. OpenClaw starts that container automatically when a sandboxed session uses the browser tool.

Your flow should be:

1. Build the image once, as you did.
2. Put the sandbox config in ~/.openclaw/openclaw.json.
3. Restart the gateway.
4. Start/use a session that is actually sandboxed.
   • With mode: "non-main", your main local session may not be sandboxed.
   • Discord/forum sessions usually count as non-main, so they should be sandboxed.
5. Ask the agent to browse something. In a sandboxed session, browser calls default to the sandbox browser. Explicitly, tool calls use target: "sandbox"; target: "host" only works because you set allowHostControl: true.

For checking it:

openclaw --version

openclaw sandbox explain
openclaw sandbox list
openclaw browser status
openclaw logs --follow

A couple config notes from the docs:

• sandbox.browser.enabled: true is the switch for Chromium-in-container.
• You don’t need root-level browser.enabled just for the sandbox browser.
• The sandbox browser has its own default Docker network: openclaw-sandbox-browser. Using bridge works, but the dedicated network is the safer default unless you specifically need bridge access.
• OpenClaw injects a short-lived noVNC observer URL into the agent context when available, so you can watch the sandbox browser if noVNC is enabled.

Docs: https://docs.openclaw.ai/gateway/sandboxing#images-and-setup and https://docs.openclaw.ai/gateway/config-agents#sandbox-details

If it doesn’t launch, paste openclaw --version, openclaw sandbox explain, and the relevant openclaw logs --follow error. Also, for “has anyone used this in practice?” style experience reports, #users-helping-users is a good place to ask too.

[heady iris]

I am already able to use the regular sandbox normally. However, I don't know how to use the browser sandbox.

Are there more specific steps? Is there any configuration missing?

[wicked heart]

Got it — yes, there are a few more specific “gotchas” for the browser sandbox.

Minimal config should look roughly like this:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // or "all" for testing
        backend: "docker",
        scope: "session",
        workspaceAccess: "rw",
        docker: {
          image: "openclaw-sandbox-common:bookworm-slim",
          network: "bridge"

        },
        browser: {
          enabled: true,
          image: "openclaw-sandbox-browser:bookworm-slim",
          autoStart: true,
          autoStartTimeoutMs: 12000
          // network omitted = safer default dedicated openclaw-sandbox-browser network
        }
      }
    }
  }
}

Then restart the gateway.

The key behavior:

• You do not manually start/use the browser image.
• When a sandboxed session calls the browser tool, OpenClaw starts the sandbox browser container automatically.
• In a sandboxed session, browser tool calls default to target: "sandbox".
• In a non-sandboxed session, browser calls default to the host browser instead.

So for testing, I’d temporarily set:

sandbox: {
  mode: "all",
  ...
}

Restart, then ask the agent something like:

Open https://example.com using the sandbox browser and take a screenshot.

If that works, switch back to mode: "non-main" if you prefer.

Things that commonly block it:

1. plugins.allow exists but does not include browser.

   • Either remove plugins.allow, or include browser.

2. Sandbox tool policy denies browser.

   • If you have something like tools.sandbox.tools.deny: ["browser"], remove browser from deny.
   • If you use an allowlist, add browser.

3. The current session is not actually sandboxed.

   • mode: "non-main" does not sandbox the main session.
   • Use mode: "all" briefly to prove the browser sandbox path works.