1  # Nullclaw Gateway Example
 2  
 3  Launch a [Nullclaw](https://github.com/nullclaw/nullclaw) Gateway inside an OpenSandbox instance and expose its HTTP endpoint. The script polls the gateway health check until it returns HTTP 200, then prints the reachable endpoint.
 4  
 5  ## Start OpenSandbox server [local]
 6  
 7  You can find the latest Nullclaw container image [here](https://github.com/nullclaw/nullclaw/pkgs/container/nullclaw).
 8  
 9  ### Notes (Docker runtime requirement)
10  
11  The server uses `runtime.type = "docker"` by default, so it **must** be able to reach a running Docker daemon.
12  
13  - **Docker Desktop**: ensure Docker Desktop is running, then verify with `docker version`.
14  - **Colima (macOS)**: start it first (`colima start`) and export the socket before starting the server:
15  
16  ```shell
17  export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
18  ```
19  
20  Pre-pull the Nullclaw image:
21  
22  ```shell
23  docker pull ghcr.io/nullclaw/nullclaw:latest
24  ```
25  
26  Start the OpenSandbox server (logs will stay in the terminal):
27  
28  ```shell
29  uv pip install opensandbox-server
30  opensandbox-server init-config ~/.sandbox.toml --example docker
31  opensandbox-server
32  ```
33  
34  If you see errors like `FileNotFoundError: [Errno 2] No such file or directory` from `docker/transport/unixconn.py`, it usually means the Docker unix socket is missing or Docker is not running.
35  
36  ## Create and Access the Nullclaw Sandbox
37  
38  This example is hard-coded for a quick start:
39  - OpenSandbox server: `http://localhost:8080`
40  - Image: `ghcr.io/nullclaw/nullclaw:latest`
41  - Gateway port: `3000`
42  - Timeout: `3600s`
43  
44  Install dependencies from the project root:
45  
46  ```shell
47  uv pip install opensandbox requests
48  ```
49  
50  Run the example:
51  
52  ```shell
53  uv run python examples/nullclaw/main.py
54  ```
55  
56  You should see output similar to:
57  
58  ```text
59  Creating nullclaw sandbox with image=ghcr.io/nullclaw/nullclaw:latest on OpenSandbox server http://localhost:8080...
60  [check] sandbox ready after 0.3s
61  Nullclaw gateway started. Please refer to 127.0.0.1:56234
62  ```
63  
64  The endpoint printed at the end (e.g., `127.0.0.1:56234`) is the Nullclaw Gateway address exposed from the sandbox.
65  
66  By default, Nullclaw requires pairing before authenticated endpoints (for example, `/webhook`) can be used. The `/health` endpoint remains publicly accessible.
67  
68  ## References
69  - [Nullclaw](https://github.com/nullclaw/nullclaw) — Minimal AI assistant runtime (678 KB static Zig binary)
70  - [Nullclaw Documentation](https://nullclaw.github.io) — Full documentation
71  - [OpenSandbox Python SDK](https://pypi.org/project/opensandbox/)