OpenSandbox Troubleshooting

Troubleshoot sandbox $ARGUMENTS using the opensandbox diagnostics.

There are two ways to interact with the diagnostics API: CLI (if opensandbox CLI is installed) or HTTP (curl against the server directly). Use whichever is available. The HTTP approach works regardless of how the sandbox was created (SDK, API, CLI).

Workflow

Step 1: Confirm sandbox state

CLI:

opensandbox sandbox get <sandbox-id>

HTTP:

curl http://<server-domain>/v1/sandboxes/<sandbox-id>

If the server requires authentication, add -H "OPEN-SANDBOX-API-KEY: <your-key>" to all curl commands.

Check the sandbox status (Running, Pending, Paused, Failed, etc.). If the sandbox is not found, it may have been deleted or expired.

Step 2: Get diagnostics summary (recommended first action)

CLI:

opensandbox devops summary <sandbox-id>

HTTP:

curl http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/summary

This returns a combined plain-text view of:

• Inspect: container/pod details (status, resources, network, labels)
• Events: state transitions, OOM kills, errors
• Logs: recent container output

Read the output carefully and look for common failure patterns listed below.

Step 3: Drill down if needed

If the summary is not enough, use individual endpoints for more detail:

CLI:

opensandbox devops logs <sandbox-id> --tail 500
opensandbox devops logs <sandbox-id> --since 30m
opensandbox devops inspect <sandbox-id>
opensandbox devops events <sandbox-id> --limit 100

HTTP:

# Get more log lines
curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/logs?tail=500"

# Get logs from recent time window
curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/logs?since=30m"

# Detailed container/pod inspection
curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/inspect"

# More events
curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/events?limit=100"

Step 4: Diagnose common problems

Step 5: Suggest resolution

Based on the diagnosis, suggest one of:

• Image issue: Verify image name, check registry access
• OOM: Increase memory limit in sandbox creation (e.g. memory=4Gi)
• Application error: Fix the entrypoint or application code
• Network: Check network policy, verify port configuration
• Scheduling (K8s): Check node resources, check pool availability
• execd: Update execd image version, check port conflicts

API Reference

All diagnostics endpoints return text/plain and are available at: