167 lines
4.5 KiB
Markdown
167 lines
4.5 KiB
Markdown
# ZeroClaw Development Environment
|
|
|
|
A fully containerized development sandbox for ZeroClaw agents. This environment allows you to develop, test, and debug the agent in isolation without modifying your host system.
|
|
|
|
## Directory Structure
|
|
|
|
- **`agent/`**: (Merged into root Dockerfile)
|
|
- The development image is built from the root `Dockerfile` using the `dev` stage (`target: dev`).
|
|
- Based on `debian:bookworm-slim` (unlike production `distroless`).
|
|
- Includes `bash`, `curl`, and debug tools.
|
|
- **`sandbox/`**: Dockerfile for the simulated user environment.
|
|
- Based on `ubuntu:22.04`.
|
|
- Pre-loaded with `git`, `python3`, `nodejs`, `npm`, `gcc`, `make`.
|
|
- Simulates a real developer machine.
|
|
- **`docker-compose.yml`**: Defines the services and `dev-net` network.
|
|
- **`cli.sh`**: Helper script to manage the lifecycle.
|
|
|
|
## Usage
|
|
|
|
Run all commands from the repository root using the helper script:
|
|
|
|
### 1. Start Environment
|
|
|
|
```bash
|
|
./dev/cli.sh up
|
|
```
|
|
|
|
Builds the agent from source and starts both containers.
|
|
|
|
### 2. Enter Agent Container (`zeroclaw-dev`)
|
|
|
|
```bash
|
|
./dev/cli.sh agent
|
|
```
|
|
|
|
Use this to run `zeroclaw` CLI commands manually, debug the binary, or check logs internally.
|
|
|
|
- **Path**: `/zeroclaw-data`
|
|
- **User**: `nobody` (65534)
|
|
|
|
### 3. Enter Sandbox (`sandbox`)
|
|
|
|
```bash
|
|
./dev/cli.sh shell
|
|
```
|
|
|
|
Use this to act as the "user" or "environment" the agent interacts with.
|
|
|
|
- **Path**: `/home/developer/workspace`
|
|
- **User**: `developer` (sudo-enabled)
|
|
|
|
### 4. Development Cycle
|
|
|
|
1. Make changes to Rust code in `src/`.
|
|
2. Rebuild the agent:
|
|
```bash
|
|
./dev/cli.sh build
|
|
```
|
|
3. Test changes inside the container:
|
|
```bash
|
|
./dev/cli.sh agent
|
|
# inside container:
|
|
zeroclaw --version
|
|
```
|
|
|
|
### 5. Persistence & Shared Workspace
|
|
|
|
The local `playground/` directory (in repo root) is mounted as the shared workspace:
|
|
|
|
- **Agent**: `/zeroclaw-data/workspace`
|
|
- **Sandbox**: `/home/developer/workspace`
|
|
|
|
Files created by the agent are visible to the sandbox user, and vice versa.
|
|
|
|
The agent configuration lives in `target/.zeroclaw` (mounted to `/zeroclaw-data/.zeroclaw`), so settings persist across container rebuilds.
|
|
|
|
### 6. Cleanup
|
|
|
|
Stop containers and remove volumes and generated config:
|
|
|
|
```bash
|
|
./dev/cli.sh clean
|
|
```
|
|
|
|
**Note:** This removes `target/.zeroclaw` (config/DB) but leaves the `playground/` directory intact. To fully wipe everything, manually delete `playground/`.
|
|
|
|
## Local CI/CD (Docker-Only)
|
|
|
|
Use this when you want CI-style validation without relying on GitHub Actions and without running Rust toolchain commands on your host.
|
|
|
|
### 1. Build the local CI image
|
|
|
|
```bash
|
|
./dev/ci.sh build-image
|
|
```
|
|
|
|
### 2. Run full local CI pipeline
|
|
|
|
```bash
|
|
./dev/ci.sh all
|
|
```
|
|
|
|
This runs inside a container:
|
|
|
|
- `./scripts/ci/rust_quality_gate.sh`
|
|
- `cargo test --locked --verbose`
|
|
- `cargo build --release --locked --verbose`
|
|
- `cargo deny check licenses sources`
|
|
- `cargo audit`
|
|
- Docker smoke build (`docker build --target dev ...` + `--version` check)
|
|
|
|
To run an opt-in strict lint audit locally:
|
|
|
|
```bash
|
|
./dev/ci.sh lint-strict
|
|
```
|
|
|
|
To run the incremental strict gate (changed Rust lines only):
|
|
|
|
```bash
|
|
./dev/ci.sh lint-delta
|
|
```
|
|
|
|
### 3. Run targeted stages
|
|
|
|
```bash
|
|
./dev/ci.sh lint
|
|
./dev/ci.sh lint-delta
|
|
./dev/ci.sh test
|
|
./dev/ci.sh build
|
|
./dev/ci.sh deny
|
|
./dev/ci.sh audit
|
|
./dev/ci.sh security
|
|
./dev/ci.sh docker-smoke
|
|
# Optional host-side docs gate (changed-line markdown lint)
|
|
./scripts/ci/docs_quality_gate.sh
|
|
# Optional host-side docs links gate (changed-line added links)
|
|
./scripts/ci/docs_links_gate.sh
|
|
```
|
|
|
|
Note: local `deny` focuses on license/source policy; advisory scanning is handled by `audit`.
|
|
|
|
### 4. Enter CI container shell
|
|
|
|
```bash
|
|
./dev/ci.sh shell
|
|
```
|
|
|
|
### 5. Optional shortcut via existing dev CLI
|
|
|
|
```bash
|
|
./dev/cli.sh ci
|
|
./dev/cli.sh ci lint
|
|
```
|
|
|
|
### Isolation model
|
|
|
|
- Rust compilation, tests, and audit/deny tools run in `zeroclaw-local-ci` container.
|
|
- Your host filesystem is mounted at `/workspace`; no host Rust toolchain is required.
|
|
- Cargo build artifacts are written to container volume `/ci-target` (not your host `target/`).
|
|
- Docker smoke stage uses your Docker daemon to build image layers, but build steps execute in containers.
|
|
|
|
### Build cache notes
|
|
|
|
- Both `Dockerfile` and `dev/ci/Dockerfile` use BuildKit cache mounts for Cargo registry/git data.
|
|
- Local CI reuses named Docker volumes for Cargo registry/git and target outputs.
|
|
- The CI image keeps Rust toolchain defaults from `rust:1.92-slim` and installs pinned toolchain `1.92.0` (no custom `CARGO_HOME`/`RUSTUP_HOME` overrides), preventing repeated toolchain bootstrapping on each run.
|