# OpenClaw Sandbox Base Image

Base Docker image for OpenClaw agent sandboxes. Provides a consistent, preconfigured environment with essential tooling for development, scripting, and automation.

## Features

- **OS:** Ubuntu 24.04 (LTS)
- **Languages & Runtimes:**
  - Node.js 25.9.0 (official binaries)
  - Go 1.26.0 (official binaries)
  - Python 3.12 + pip + venv
  - Rust/cargo via workspace install (if needed)
- **Tooling:** git, curl, wget, jq, ripgrep, rsync, sudo, tini, unzip, xz-utils, file
- **User setup:** Creates `sandbox` user with UID/GID matching host (configurable)
- **Workspace layout:**
  - `HOME=/workspace`
  - `GOPATH=/workspace/go`
  - `NPM_CONFIG_PREFIX=/workspace/.local`
  - `PATH` includes `/workspace/.local/bin`, `/workspace/.cargo/bin`, `/workspace/go/bin`

## Build Args

| Arg | Default | Description |
|-----|---------|-------------|
| `SANDBOX_UID` | `1001` | UID for the `sandbox` user (match host) |
| `SANDBOX_GID` | `1001` | GID for the `sandbox` group (match host) |
| `TARGETARCH` | (auto) | Target architecture (`amd64` or `arm64`). Set by Docker buildx. |

## Usage

### Build locally

```bash
docker build \
  --build-arg SANDBOX_UID=$(id -u) \
  --build-arg SANDBOX_GID=$(id -g) \
  --build-arg TARGETARCH=$(docker info --format '{{.Architecture}}') \
  -t sandbox-base-image:latest .
```

### Run

```bash
docker run -d \
  --name openclaw-sandbox \
  -v /workspace:/workspace \
  -e SANDBOX_UID=$(id -u) \
  -e SANDBOX_GID=$(id -g) \
  sandbox-base-image:latest
```

The entrypoint prepares the workspace and drops into the user environment. Default command is `sleep infinity` so you can `docker exec -it` into it.

### Entrypoint behavior

`/usr/local/bin/sandbox-entrypoint.sh` ensures:
- HOME, GOPATH, NPM_CONFIG_PREFIX, PATH are set
- standard dirs exist (`~/.local`, `~/.config`, `~/.npm`, `~/.cargo/bin`, `~/go/bin`)
- npm prefix/cache are coerced into the workspace home via `~/.npmrc`
- then execs the command (default: `sleep infinity`)

## Container Registry

Images are built and pushed to the Gitea container registry by CI:

- **Registry:** `git.danhenry.dev:5050`
- **Repository:** `TheLab/sandbox-base-image`
- **Tags:** `latest`, plus commit SHAs for non-main branches; on `main` also `stable`

## Development

- Adjust versions via `ARG NODE_VERSION` and `ARG GO_VERSION` in the Dockerfile.
- Keep apt package list minimal; add only what agents actually use.

## Notes

- The image intentionally avoids global npm/yarn/global installs; prefix is `/workspace/.local` to keep all user-installed tools inside the mounted workspace.
- Sudo is configured for passwordless operation for the `sandbox` user.