Secure AI Agents with OpenShell
30 MIN
Isolate OpenClaw with kernel-level policies and route inference to a local model
| Symptom | Cause | Fix |
|---|---|---|
openshell status shows "Connection refused" | The openshell-gateway systemd user service is not running, or Docker socket is not accessible from the user service | Start it: systemctl --user start openshell-gateway. Check logs: journalctl --user -u openshell-gateway --no-pager -n 50. If the service cannot reach Docker, fix socket access with sudo setfacl -m u:$USER:rw /var/run/docker.sock, then restart the service |
openshell gateway start fails with "connection refused" or Docker errors | Docker is not running | Start Docker with sudo systemctl start docker or launch Docker Desktop, then retry openshell gateway start |
openshell status shows gateway as unhealthy | Gateway service or container crashed / failed to initialize | Prefer systemctl --user restart openshell-gateway and inspect journalctl --user -u openshell-gateway --no-pager -n 50. If you started the gateway with the CLI, run openshell gateway destroy then openshell gateway start. Check Docker with docker ps -a and docker logs <container-id> |
openshell sandbox create --from openclaw fails to build | Network issue pulling the community sandbox or Dockerfile build failure | Check internet connectivity. Retry the command. If the build fails on a specific package, check if the base image is compatible with your Docker version |
Sandbox is in Error phase after creation | Policy validation failed or container startup crashed | Run openshell logs <sandbox-name> to see error details. Common causes: invalid policy YAML, missing provider credentials, or port conflicts |
Agent cannot reach inference.local inside the sandbox | Inference routing not configured or provider unreachable | Run openshell inference get to verify the provider and model are set. From the host, test the server: curl -s http://localhost:8000/v1/models. Ensure the provider OPENAI_BASE_URL uses the hardware IP address (not localhost), since the gateway runs inside Docker |
| 503 verification failed or timeout when gateway/sandbox accesses vLLM on the host | Provider URL points at localhost, firewall blocking port 8000, model still loading, or first-request compile | Confirm the server was started with --host 0.0.0.0. Confirm the provider URL uses the hardware IP from hostname -I. Warm up with a chat completion before openshell inference set. Allow port 8000 through the host firewall if needed: sudo ufw allow 8000/tcp (then sudo ufw reload). Use --no-verify only after confirming the host API works |
| Agent's outbound connections are all denied | Default policy does not include the required endpoints | Monitor denials with openshell logs <sandbox-name> --tail --source sandbox. Pull the current policy with openshell policy get <sandbox-name> --full, add the needed host/port under network_policies, and push with openshell policy set <sandbox-name> --policy <file> --wait |
| "Permission denied" or Landlock errors inside the sandbox | Agent trying to access a path not in read_only or read_write filesystem policy | Pull the current policy and add the path to read_write (or read_only if read access is sufficient). Push the updated policy. Note: filesystem policy is static and requires sandbox recreation |
| vLLM OOM or very slow inference | Model too large for available memory or GPU contention | Free GPU memory (close other GPU workloads), choose a smaller model, or lower --gpu-memory-utilization / --max-model-len. Monitor with nvidia-smi |
openshell sandbox connect hangs or times out | Sandbox not in Ready phase | Run openshell sandbox get <sandbox-name> to check the phase. If stuck in Provisioning, wait or check logs. If in Error, delete and recreate the sandbox. If phase is Unspecified during onboarding, complete the interactive wizard with openshell sandbox connect <sandbox-name> |
| Policy push returns exit code 1 (validation failed) | Malformed YAML or invalid policy fields | Check the YAML syntax. Common issues: paths not starting with /, .. traversal in paths, root as run_as_user, or endpoints missing required host/port fields. Fix and re-push |
openshell gateway start fails with "K8s namespace not ready" / timed out waiting for namespace | The k3s cluster inside the Docker container takes longer to bootstrap than the CLI timeout allows | Check whether the container is still progressing: docker ps --filter name=openshell. Inspect k3s state: docker exec <container> sh -c "KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get ns" and kubectl get pods -A. If pods are still creating, wait and retry openshell status. If it does not recover, openshell gateway destroy and retry openshell gateway start. Ensure Docker has enough memory and disk |
openshell status says "No gateway configured" | Gateway service never started / was disabled, or CLI start timed out before saving local config | For the systemd path: systemctl --user start openshell-gateway then openshell status (optionally systemctl --user enable openshell-gateway). For the CLI/Docker path: check docker ps --filter name=openshell; if healthy, retry openshell gateway start; if unhealthy, docker rm -f <container>, then openshell gateway destroy followed by openshell gateway start |
| TLS / certificate errors when adding a remote gateway by LAN IP | Gateway certificate is valid for openshell, localhost, and 127.0.0.1 — not the LAN IP | Map openshell to the hardware IP in /etc/hosts, then register with openshell gateway add https://openshell:8080 --remote <user>@<hardware-ip> |
NOTE
Some hardware platforms use Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU. With many applications still updating to take advantage of UMA, you may encounter memory issues even when within capacity. If that happens, manually flush the buffer cache with:
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'