Skip to content

Latest commit

 

History

History
 
 

nullclaw

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
main.py
main.py
 
 

README.md

Nullclaw Gateway Example

Launch a 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.

Start OpenSandbox server [local]

You can find the latest Nullclaw container image here.

Notes (Docker runtime requirement)

The server uses runtime.type = "docker" by default, so it must be able to reach a running Docker daemon.

  • Docker Desktop: ensure Docker Desktop is running, then verify with docker version.
  • Colima (macOS): start it first (colima start) and export the socket before starting the server:
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

Pre-pull the Nullclaw image:

docker pull ghcr.io/nullclaw/nullclaw:latest

Start the OpenSandbox server (logs will stay in the terminal):

uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server

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.

Create and Access the Nullclaw Sandbox

This example is hard-coded for a quick start:

  • OpenSandbox server: http://localhost:8080
  • Image: ghcr.io/nullclaw/nullclaw:latest
  • Gateway port: 3000
  • Timeout: 3600s

Install dependencies from the project root:

uv pip install opensandbox requests

Run the example:

uv run python examples/nullclaw/main.py

You should see output similar to:

Creating nullclaw sandbox with image=ghcr.io/nullclaw/nullclaw:latest on OpenSandbox server http://localhost:8080...
[check] sandbox ready after 0.3s
Nullclaw gateway started. Please refer to 127.0.0.1:56234

The endpoint printed at the end (e.g., 127.0.0.1:56234) is the Nullclaw Gateway address exposed from the sandbox.

By default, Nullclaw requires pairing before authenticated endpoints (for example, /webhook) can be used. The /health endpoint remains publicly accessible.

References