--- title: "Secure AI Agents with OpenShell — Troubleshooting" canonical: "https://build.nvidia.com/spark/openshell/troubleshooting.md" --- | 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 ` | | `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 ` 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 --tail --source sandbox`. Pull the current policy with `openshell policy get --full`, add the needed host/port under `network_policies`, and push with `openshell policy set --policy --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 ` 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 ` | | 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 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 `, 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 @` | > [!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: > ```bash > sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches' > ```