* feat(docker): add opt-in sandbox support for Docker deployments
Enable Docker-based sandbox isolation via OPENCLAW_SANDBOX=1 env var
in docker-setup.sh. This is a prerequisite for agents.defaults.sandbox
to function in any Docker deployment (self-hosted, Hostinger, DigitalOcean).
Changes:
- Dockerfile: add OPENCLAW_INSTALL_DOCKER_CLI build arg (~50MB, opt-in)
- docker-compose.yml: add commented-out docker.sock mount with docs
- docker-setup.sh: auto-detect Docker socket, inject mount, detect GID,
build sandbox image, configure sandbox defaults, add group_add
All changes are opt-in. Zero impact on existing deployments.
Usage: OPENCLAW_SANDBOX=1 ./docker-setup.sh
Closes#29933
Related: #7575, #7827, #28401, #10361, #12505, #28326
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address code review feedback on sandbox support
- Persist OPENCLAW_SANDBOX, DOCKER_GID, OPENCLAW_INSTALL_DOCKER_CLI
to .env via upsert_env so group_add survives re-runs
- Show config set errors instead of swallowing them silently;
report partial failure when sandbox config is incomplete
- Warn when Dockerfile.sandbox is missing but sandbox config
is still applied (sandbox image won't exist)
- Fix non-canonical whitespace in apt sources.list entry
by using printf instead of echo with line continuation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove `local` outside function and guard sandbox behind Docker CLI check
- Remove `local` keyword from top-level `sandbox_config_ok` assignment
which caused script exit under `set -euo pipefail` (bash `local`
outside a function is an error)
- Add Docker CLI prerequisite check for pre-built (non-local) images:
runs `docker --version` inside the container and skips sandbox setup
with a clear warning if the CLI is missing
- Split sandbox block so config is only applied after prerequisites pass
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: defer docker.sock mount until sandbox prerequisites pass
Move Docker socket mounting from the early setup phase (before image
build/pull) to a dedicated compose overlay created only after:
1. Docker CLI is verified inside the container image
2. /var/run/docker.sock exists on the host
Previously the socket was mounted optimistically at startup, leaving
the host Docker daemon exposed even when sandbox setup was later
skipped due to missing Docker CLI. Now the gateway starts without
the socket, and a docker-compose.sandbox.yml overlay is generated
only when all prerequisites pass. The gateway restart at the end of
sandbox setup picks up both the socket mount and sandbox config.
Also moves group_add from write_extra_compose() into the sandbox
overlay, keeping all sandbox-specific compose configuration together.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(docker): fix sandbox docs URL in setup output
* Docker: harden sandbox setup fallback behavior
* Tests: cover docker-setup sandbox edge paths
* Docker: roll back sandbox mode on partial config failure
* Tests: assert sandbox mode rollback on partial setup
* Docs: document Docker sandbox bootstrap env controls
* Changelog: credit Docker sandbox bootstrap hardening
* Update CHANGELOG.md
* Docker: verify Docker apt signing key fingerprint
* Docker: avoid sandbox overlay deps during policy writes
* Tests: assert no-deps sandbox rollback gateway recreate
* Docs: mention OPENCLAW_INSTALL_DOCKER_CLI in Docker env vars
---------
Co-authored-by: Jakub Karwowski <jakubkarwowski@Mac.lan>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
* docs(gateway): document Docker bridge networking and loopback bind caveat
The default loopback bind makes the gateway unreachable with Docker
bridge networking because port-forwarded traffic arrives on eth0, not
lo. Add a note in both the Dockerfile and the configuration reference
explaining the workarounds (--network host or bind: lan).
Fixes#27950
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(docker): note legacy gateway.bind alias migration
* docs(gateway): clarify legacy bind alias auto-migration
* docs(docker): require bind mode values in gateway.bind
* docs(gateway): avoid bind alias auto-migration claim
* changelog: add #28001 docker bind docs credit
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
* fix(docker): harden /app/extensions permissions to 755
Bundled extension directories shipped as world-writable (mode 777)
in the Docker image. The plugin security scanner blocks any world-
writable path with:
WARN: blocked plugin candidate: world-writable path
(/app/extensions/memory-core, mode=777)
Add chmod -R 755 /app/extensions in the final USER root RUN step so
all bundled extensions are readable but not world-writable. This runs
as root before switching back to the node user, matching the pattern
already used for chmod 755 /app/openclaw.mjs.
Fixes#30139
* fix(docker): normalize plugin and agent path permissions
* docs(changelog): add docker permissions entry for #30191
* Update CHANGELOG.md
---------
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
* fix(docker): pin base images to SHA256 digests for supply chain security
Pin all 9 Dockerfiles to immutable SHA256 digests to prevent supply chain
attacks where a compromised upstream image could be silently pulled into
production builds.
Also add Docker ecosystem to Dependabot configuration for automated
digest updates.
Images pinned:
- node:22-bookworm@sha256:cd7bcd2e7a1e6f72052feb023c7f6b722205d3fcab7bbcbd2d1bfdab10b1e935
- node:22-bookworm-slim@sha256:3cfe526ec8dd62013b8843e8e5d4877e297b886e5aace4a59fec25dc20736e45
- debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
- ubuntu:24.04@sha256:cd1dba651b3080c3686ecf4e3c4220f026b521fb76978881737d24f200828b2b
Fixes#7731
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test(docker): add digest pinning regression coverage
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Address review feedback:
- Move the OPENCLAW_INSTALL_BROWSER block after pnpm install so
playwright-core is available in node_modules
- Use node /app/node_modules/playwright-core/cli.js instead of
npx playwright to avoid npm override conflicts in Docker
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a build arg OPENCLAW_INSTALL_BROWSER that, when set, pre-installs
Chromium (via Playwright) and Xvfb into the Docker image. This eliminates
the 60-90 second Playwright install that otherwise happens on every
container start when browser features are used.
Usage:
docker build --build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:browser .
Without the build arg, behavior is unchanged (no Chromium in image).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds an ENTRYPOINT script that runs user-provided init scripts from
/openclaw-init.d/ before starting the gateway. This is the standard
Docker pattern (used by nginx, postgres, etc.) for customizing container
startup without overriding the entire entrypoint.
Usage:
docker run -v ./my-init-scripts:/openclaw-init.d:ro openclaw
Scripts must be executable. Non-executable files are skipped with a
warning. Scripts run in alphabetical order with output prefixed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Address review feedback: remove 2>/dev/null so that if the LanceDB
native binary download fails, the error is visible in Docker build
logs for debugging rather than silently swallowed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The memory-lancedb extension declares openai and @lancedb/lancedb as
dependencies, but these may not be available at runtime due to pnpm
hoisting behavior with native bindings. This adds an explicit install
step after the build to ensure the extension's dependencies are present.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Addresses review feedback: --bind lan requires auth token, so default
CMD should bind to loopback only.
For container platforms needing LAN binding for health checks:
1. Set OPENCLAW_GATEWAY_TOKEN env var
2. Override CMD: ["node","dist/index.js","gateway","--allow-unconfigured","--bind","lan"]
The Dockerfile CMD runs without arguments, causing the CLI to print
help and exit with code 1. This breaks deployment on container
platforms (Render, Railway, Fly.io, etc.) that rely on the CMD.
Changes:
- Add `gateway` subcommand to start the server
- Add `--allow-unconfigured` to allow startup without config file
- Add `--bind lan` to bind to 0.0.0.0 instead of localhost
(required for container health checks)
Fixes#5685
- Add USER node directive to Dockerfile for non-root container execution
- Update SECURITY.md with Node.js version requirements (CVE-2025-59466, CVE-2026-21636)
- Add Docker security best practices documentation
- Document detect-secrets usage for local security scanning
Reviewed-by: Agents Council (5/5 approval)
Security-Score: 8.8/10
Watchdog-Verdict: SAFE WITH CONDITIONS
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
