opensandbox-cli 0.1.0__py3-none-any.whl

opensandbox_cli/skills/opensandbox-network-egress.md

@@ -0,0 +1,179 @@
+---
+name: network-egress
+description: Use OpenSandbox egress commands to inspect and patch runtime outbound network policy for a sandbox. Trigger when users want to allow or deny domains, confirm current egress rules, or debug outbound network access problems caused by policy.
+---
+
+# OpenSandbox Network Egress
+
+Manage outbound network access with `osb egress`. Treat runtime egress patching as a policy workflow, not just a one-line command. Always inspect current state, patch only what is needed, then verify both policy text and actual network behavior.
+
+## When To Use
+
+- the user wants to see current egress rules for a sandbox
+- the user wants to allow or deny one or more outbound domains for an existing sandbox
+- the user reports outbound access issues and runtime policy may be the cause
+- the user wants an exact OpenSandbox command for runtime network policy changes
+
+## Configuration Resolution
+
+Before suggesting egress commands, resolve the active OpenSandbox connection configuration:
+
+```bash
+osb config show -o json
+```
+
+Check the resolved values for:
+
+- `domain`
+- `api_key`
+- `protocol`
+
+`osb config show` redacts the API key. Use it to confirm the effective target, not to recover the credential itself.
+
+Do not assume the user configures OpenSandbox only through environment variables. Work from the resolved configuration that the CLI will actually use.
+
+Hard stop:
+
+```bash
+osb config show -o json
+```
+
+If `domain` is missing, stop and set it before policy changes:
+
+```bash
+osb config set connection.domain <host:port> -o json
+osb config show -o json
+```
+
+If auth is required and `api_key` is missing, stop and set it before policy changes:
+
+```bash
+osb config set connection.api_key <api-key> -o json
+osb config show -o json
+```
+
+## Policy Model
+
+Runtime egress policy consists of:
+
+- `defaultAction`
+  The fallback action when no rule matches
+- `egress`
+  An ordered list of allow or deny rules
+
+Important semantics:
+
+- if `defaultAction` is omitted, the policy model defaults to `deny`
+- runtime patching uses merge semantics; it is not a full policy replacement workflow
+- targets should be domain-based, such as `pypi.org` or `*.example.com`
+- do not assume IP or CIDR targets are supported in this workflow
+
+Use `osb egress patch` for already-created sandboxes. Use `osb sandbox create --network-policy-file ...` when the user wants to define policy at sandbox creation time.
+
+## Golden Paths
+
+Inspect and patch:
+
+```bash
+osb egress get <sandbox-id> -o json
+osb egress patch <sandbox-id> --rule allow=pypi.org -o json
+osb egress get <sandbox-id> -o json
+```
+
+Inspect, patch, and verify actual behavior:
+
+```bash
+osb egress get <sandbox-id> -o json
+osb egress patch <sandbox-id> --rule allow=www.github.com --rule deny=pypi.org -o json
+osb egress get <sandbox-id> -o json
+osb command run <sandbox-id> -o raw -- curl -I https://www.github.com
+osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
+```
+
+## Inspect Current Policy
+
+Start by reading the current runtime policy:
+
+```bash
+osb egress get <sandbox-id> -o json
+```
+
+Use this before patching whenever the existing state matters.
+
+## Patch Runtime Rules
+
+Patch only the rules the user actually asked for:
+
+```bash
+osb egress patch <sandbox-id> --rule allow=pypi.org -o json
+osb egress patch <sandbox-id> --rule deny=internal.example.com -o json
+osb egress patch <sandbox-id> --rule allow=*.example.com -o json
+osb egress patch <sandbox-id> --rule allow=www.github.com --rule deny=pypi.org -o json
+```
+
+Rules:
+
+- keep patches narrow and auditable
+- express changes as explicit `allow` or `deny` entries
+- do not present patching as a full replacement of the policy object
+
+## Behavior Verification
+
+Do not stop at policy text if the user is debugging connectivity. Verify runtime behavior with actual commands:
+
+```bash
+osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
+osb command run <sandbox-id> -o raw -- curl -I https://www.github.com
+```
+
+Use:
+
+- `egress get` to confirm the current rule set
+- `osb command run ... -o raw -- curl ...` to verify whether outbound access is actually allowed or denied
+
+## Runtime Notes
+
+- use lifecycle create-time policy files when the sandbox has not been created yet
+- use `osb egress patch` only for an already-running or already-created sandbox
+- if network access is still wrong after a correct patch, continue with `sandbox-troubleshooting` instead of assuming the patch command failed silently
+
+## Response Pattern
+
+Structure the answer as:
+
+1. exact `osb egress` command
+2. what policy change it applies
+3. the verification command to run next
+
+Keep command examples concrete and ready to paste.
+
+## Minimal Closed Loops
+
+Allow one domain and verify:
+
+```bash
+osb egress get <sandbox-id> -o json
+osb egress patch <sandbox-id> --rule allow=pypi.org -o json
+osb egress get <sandbox-id> -o json
+osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
+```
+
+Flip behavior between two domains:
+
+```bash
+osb egress get <sandbox-id> -o json
+osb egress patch <sandbox-id> --rule allow=www.github.com --rule deny=pypi.org -o json
+osb egress get <sandbox-id> -o json
+osb command run <sandbox-id> -o raw -- curl -I https://www.github.com
+osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
+```
+
+## Best Practices
+
+- resolve the active connection configuration before patching policy on a specific server
+- prefer `osb config show` over checking isolated environment variables
+- inspect before patching
+- patch only the minimum required domains
+- verify actual behavior, not just rule text
+- prefer explicit domain targets over broad wildcards unless the user truly needs them
+- prefer create-time policy files for initial sandbox provisioning and runtime patching for later adjustment

opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md

@@ -0,0 +1,305 @@
+---
+name: sandbox-lifecycle
+description: Use OpenSandbox CLI lifecycle commands to create, inspect, verify, renew, pause, resume, expose, and terminate sandboxes. Trigger when users want help provisioning a sandbox, choosing create flags, checking runtime state, retrieving endpoints, or safely cleaning up sandboxes.
+---
+
+# OpenSandbox Sandbox Lifecycle
+
+Use OpenSandbox lifecycle commands directly instead of giving generic container advice. Prefer a verified lifecycle flow over isolated commands.
+
+## When To Use
+
+- the user wants to create a sandbox for a task or workflow
+- the user needs to inspect sandbox state or health
+- the user wants to expose a service port through an OpenSandbox endpoint
+- the user wants to renew, pause, resume, or terminate a sandbox
+- the user is unsure which create flags or file-based inputs to use
+
+## Configuration Resolution
+
+Before giving lifecycle commands, resolve the active OpenSandbox connection configuration:
+
+```bash
+osb config show -o json
+```
+
+Check the resolved values for:
+
+- `domain`
+- `api_key`
+- `protocol`
+- `use_server_proxy` when endpoint routing matters
+
+`osb config show` redacts the API key. Use it to confirm which server and protocol the CLI will target, not to recover credentials.
+
+Do not focus only on environment variables. `osb config show` already reflects the effective configuration after applying CLI flags, environment variables, config file values, and defaults.
+
+Hard stop:
+
+```bash
+osb config show -o json
+```
+
+If `domain` is missing, stop and set it before lifecycle commands:
+
+```bash
+osb config set connection.domain <host:port> -o json
+osb config show -o json
+```
+
+If auth is required and `api_key` is missing, stop and set it before lifecycle commands:
+
+```bash
+osb config set connection.api_key <api-key> -o json
+osb config show -o json
+```
+
+If the effective target is clear, then continue with lifecycle commands.
+
+## Preflight Checks
+
+Run these checks before lifecycle commands:
+
+```bash
+osb --version
+osb config show -o json
+```
+
+If `osb` is missing, try a project-local entrypoint:
+
+```bash
+.venv/bin/osb --version
+.venv/bin/osb config show -o json
+```
+
+Use the results to classify the situation:
+
+- CLI available
+- config resolves
+- target looks plausible for the current environment
+
+## Golden Path
+
+Use this as the default lifecycle flow unless the user asks for a narrower action:
+
+```bash
+osb config show -o json
+osb sandbox create --image python:3.12 --timeout 30m -o json
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+```
+
+If the sandbox is intended to serve traffic on a known port, continue with:
+
+```bash
+osb sandbox endpoint <sandbox-id> --port 8080 -o json
+```
+
+This sequence is safer than stopping at `sandbox get`, because `get` confirms object state while `health` confirms the sandbox is actually reachable through the execd health path.
+
+## Create Options
+
+Start with the narrowest create command that matches the request:
+
+```bash
+osb sandbox create --image python:3.12 -o json
+osb sandbox create --image node:20 --timeout 30m -o json
+osb sandbox create --image my-registry.example.com/team/app:latest --image-auth-username alice --image-auth-password <token> -o json
+osb sandbox create --image python:3.12 --timeout none -o json
+osb sandbox create --image python:3.12 --entrypoint python --entrypoint -m --entrypoint http.server -o json
+osb sandbox create --image python:3.12 --extension storage.id=abc123 -o json
+osb sandbox create --image python:3.12 --ready-timeout 90s -o json
+osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json
+osb sandbox create --image python:3.12 --volumes-file volumes.json -o json
+```
+
+Use these options deliberately:
+
+- `--image`: required unless the CLI already has `defaults.image` configured
+- `--image-auth-username` and `--image-auth-password`: use together when the image is in a private registry
+- `--timeout`: recommended for most temporary workloads so sandboxes do not linger indefinitely
+- `--timeout none`: disable automatic expiration and switch the sandbox to manual cleanup mode
+- omit `--timeout`: use `defaults.timeout` when configured; otherwise the request falls back to the SDK/server default TTL
+- `--entrypoint`: repeat the flag once per argv item; do not use JSON or shell-wrapped command strings
+- `--extension`: repeat for opaque extension key-value pairs that should be passed through as-is
+- `--ready-timeout`: increase this when the image or workload needs more startup time
+- `--skip-health-check`: use only when the user explicitly wants object creation without waiting for readiness; do not use it to mask startup problems
+
+If the user does not specify an image, recommend one that matches the runtime they need instead of guessing silently.
+
+## JSON Shapes
+
+When recommending `--network-policy-file` or `--volumes-file`, always show the JSON shape instead of assuming the user knows it.
+
+Example `network-policy.json`:
+
+```json
+{
+  "defaultAction": "deny",
+  "egress": [
+    {
+      "action": "allow",
+      "target": "pypi.org"
+    },
+    {
+      "action": "allow",
+      "target": "files.pythonhosted.org"
+    }
+  ]
+}
+```
+
+Example `volumes-host.json`:
+
+```json
+[
+  {
+    "name": "workspace-data",
+    "host": {
+      "path": "/tmp/opensandbox-data"
+    },
+    "mountPath": "/workspace/data",
+    "readOnly": false
+  }
+]
+```
+
+Example `volumes-pvc.json`:
+
+```json
+[
+  {
+    "name": "shared-models",
+    "pvc": {
+      "claimName": "shared-models-pvc"
+    },
+    "mountPath": "/workspace/models",
+    "readOnly": true
+  }
+]
+```
+
+Prefer `pvc` when the environment supports it and the user needs a more portable storage definition. Use `host` when the user explicitly needs a host-path bind mount and the server has been configured to allow that path.
+
+## Verification
+
+Use verification commands in this order:
+
+```bash
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+osb sandbox metrics <sandbox-id> -o json
+osb sandbox metrics <sandbox-id> --watch -o raw
+```
+
+Use:
+
+- `sandbox get` to inspect the current lifecycle state and metadata
+- `sandbox health` to confirm the sandbox is usable
+- `sandbox metrics` for a point-in-time resource snapshot
+- `sandbox metrics --watch` when the user wants live CPU and memory updates while diagnosing load or pressure
+
+If the user needs a public or routed port, verify it explicitly:
+
+```bash
+osb sandbox endpoint <sandbox-id> --port 8080 -o json
+```
+
+## Lifecycle Actions
+
+Use these commands for ongoing lifecycle management:
+
+```bash
+osb sandbox list -o json
+osb sandbox list --state running --state paused -o json
+osb sandbox renew <sandbox-id> --timeout 30m -o json
+osb sandbox pause <sandbox-id> -o json
+osb sandbox resume <sandbox-id> -o json
+osb sandbox kill <sandbox-id> -o json
+```
+
+Rules:
+
+- use `sandbox list` for discovery or filtering, not single-sandbox verification
+- `sandbox list --state` accepts known lifecycle states case-insensitively
+- use `renew` before long-running work instead of waiting for expiry
+- use `pause` only when the workload can tolerate suspension
+- use `kill` when cleanup is the real goal; do not leave orphaned sandboxes behind
+
+## Runtime Notes
+
+- `renew` resets the expiration to approximately `now + timeout`; treat it as a fresh TTL, not a simple additive extension to the old timestamp
+- `create --timeout none` means no automatic expiration; cleanup becomes an explicit `kill` responsibility
+- `create` without `--timeout` does not mean manual cleanup; it uses `defaults.timeout` first and otherwise leaves TTL selection to the SDK/server default
+- `pause` and `resume` may depend on the underlying runtime; if the runtime does not support them, avoid promising they will work
+- host-path volumes depend on server-side allowed host path configuration
+- if creation fails or the sandbox never becomes healthy, switch to `sandbox-troubleshooting` instead of adding more create flags blindly
+
+## Response Pattern
+
+Structure the answer as:
+
+1. exact command to run
+2. what state change or verification result to expect
+3. the next lifecycle command if the workflow continues
+
+Keep command examples concrete and ready to paste.
+
+## Minimal Closed Loops
+
+Create and verify readiness:
+
+```bash
+osb sandbox create --image python:3.12 --timeout 30m -o json
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+```
+
+Create a service sandbox and retrieve its endpoint:
+
+```bash
+osb sandbox create --image python:3.12 --timeout 30m -o json
+osb sandbox health <sandbox-id> -o json
+osb sandbox endpoint <sandbox-id> --port 8080 -o json
+```
+
+Create with network policy:
+
+```bash
+osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+```
+
+Renew before long work:
+
+```bash
+osb sandbox renew <sandbox-id> --timeout 30m -o json
+osb sandbox get <sandbox-id> -o json
+```
+
+Pause and confirm state:
+
+```bash
+osb sandbox pause <sandbox-id> -o json
+osb sandbox get <sandbox-id> -o json
+```
+
+Resume and verify health:
+
+```bash
+osb sandbox resume <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+```
+
+## Best Practices
+
+- resolve the active connection configuration before assuming which server the command will hit
+- prefer `osb config show` over checking individual environment variables in isolation
+- confirm whether the user wants to keep, override, or persist connection settings before changing them
+
+- Prefer explicit `--image` and `--timeout` when demonstrating commands
+- Prefer `health` over assuming readiness from `create` output alone
+- Prefer `endpoint` over telling the user to guess host/port mappings
+- Prefer `pvc` over `host` when portability matters
+- Prefer troubleshooting over `--skip-health-check` when startup is failing

opensandbox_cli/skills/opensandbox-sandbox-troubleshooting.md

@@ -0,0 +1,177 @@
+---
+name: sandbox-troubleshooting
+description: Use OpenSandbox CLI state, health, summary, inspect, events, and logs to investigate failed, unhealthy, or unreachable sandboxes. Trigger when users report startup failures, crashes, OOM, image pull problems, pending sandboxes, network issues, or an unresponsive sandbox and want root cause plus next actions.
+---
+
+# OpenSandbox Sandbox Troubleshooting
+
+Investigate the reported sandbox before proposing a fix. Prefer evidence from OpenSandbox state, health checks, summary output, and diagnostics streams over speculation.
+
+## Inputs To Collect
+
+Capture these from the user request or surrounding context before running commands:
+
+- sandbox ID or an unambiguous short ID
+- whether `osb` or `opensandbox` CLI is available locally
+- any reported symptom: pending forever, crash, OOM, unreachable service, bad image, failed exec, etc.
+
+If the sandbox ID is missing, ask for it first.
+
+## Configuration Resolution
+
+Before troubleshooting a sandbox, resolve the active OpenSandbox connection configuration:
+
+```bash
+osb config show -o json
+```
+
+Check the resolved values for:
+
+- `domain`
+- `api_key`
+- `protocol`
+- `use_server_proxy` when endpoint routing or proxy behavior may matter
+
+`osb config show` redacts the API key. Use it to confirm the effective target server and protocol before troubleshooting.
+
+If `domain` is missing, stop and set it first:
+
+```bash
+osb config set connection.domain <host:port> -o json
+osb config show -o json
+```
+
+If auth is required and `api_key` is missing, stop and set it first:
+
+```bash
+osb config set connection.api_key <api-key> -o json
+osb config show -o json
+```
+
+Use raw HTTP only after domain, protocol, and API key expectations are explicit.
+
+## Operating Rules
+
+- start with the highest-signal commands first: sandbox state, sandbox health, then diagnostics summary
+- use CLI commands when `osb` is available because they are shorter and usually already authenticated
+- use HTTP only when the CLI is unavailable or the user is clearly working from raw API access
+- distinguish observed facts from inference and quote the field, event, or log line that supports the diagnosis
+- separate sandbox/runtime failures from workload/application failures before suggesting a fix
+- do not paper over readiness problems with `--skip-health-check`
+- end with a likely root cause and 1-3 concrete remediation steps
+
+## Triage Order
+
+Use this order by default:
+
+```bash
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+osb devops summary <sandbox-id> -o raw
+```
+
+Then drill down only where the summary points:
+
+```bash
+osb devops inspect <sandbox-id> -o raw
+osb devops events <sandbox-id> --limit 100 -o raw
+osb devops logs <sandbox-id> --tail 500 -o raw
+osb devops logs <sandbox-id> --since 30m -o raw
+```
+
+## Diagnostics Streams
+
+Important properties of the diagnostics commands:
+
+- `summary` is the broadest starting point because it combines inspect output, event history, and recent logs
+- `inspect`, `events`, and `logs` are detailed streams used after the broad summary
+- diagnostics commands return plain-text output, not structured SDK model objects
+- quote concrete lines from diagnostics output instead of summarizing vaguely
+
+Use:
+
+- `inspect` for container state, exit code, restart count, resources, ports, and runtime metadata
+- `events` for scheduling failures, image pull issues, restarts, OOM kills, and probe transitions
+- `logs` for application errors, missing binaries, bad entrypoints, startup hangs, and health-check failures
+
+## Symptom To Command Mapping
+
+Use the first command that best matches the reported symptom:
+
+| Symptom | First command | What to confirm next |
+| --- | --- | --- |
+| pending forever or stuck creating | `osb devops events <sandbox-id> --limit 100 -o raw` | image pull errors, scheduling failures, admission errors |
+| image pull failure | `osb devops events <sandbox-id> --limit 100 -o raw` | image name, tag, registry auth |
+| crash loop or repeated restarts | `osb devops logs <sandbox-id> --tail 200 -o raw` | `osb devops inspect <sandbox-id> -o raw` for exit code and restart count |
+| suspected OOM or exit code issue | `osb devops inspect <sandbox-id> -o raw` | `OOMKilled`, exit code, resource limits |
+| endpoint unreachable or connection refused | `osb sandbox health <sandbox-id> -o json` | `osb sandbox endpoint <sandbox-id> --port <port> -o json` and then `osb devops logs <sandbox-id> --tail 200 -o raw` |
+| outbound network access failure | `osb sandbox health <sandbox-id> -o json` | check service behavior, then switch to `network-egress` if the issue is egress policy related |
+
+## Diagnosis Playbooks
+
+### Image Pull Failure
+
+- first evidence: `events` shows `ImagePullBackOff`, `ErrImagePull`, or auth failures
+- confirming evidence: sandbox stays `Pending` or never reaches healthy state
+- likely cause: bad image reference or missing registry credentials
+- next actions: verify image URI and tag, fix registry auth, recreate the sandbox
+
+### OOM Kill
+
+- first evidence: `inspect` shows `OOMKilled: True` or exit code `137`
+- confirming evidence: events mention container killed due to out-of-memory
+- likely cause: memory limit too low for the workload
+- next actions: increase memory, rerun the workload, compare peak workload memory with the configured limit
+
+### Crash Loop Or Bad Entrypoint
+
+- first evidence: `logs` show startup exceptions, missing binaries, or permission errors
+- confirming evidence: `inspect` shows repeated restarts, exit code `126`, or exit code `127`
+- likely cause: bad entrypoint, missing executable, or application crash on boot
+- next actions: fix the command or image contents, correct file permissions, redeploy or recreate
+
+### Endpoint Or Service Unreachable
+
+- first evidence: sandbox is `Running` but client requests fail or connection is refused
+- confirming evidence: `sandbox endpoint <id> --port <port>` is missing, wrong, or points to a service that is not listening
+- likely cause: wrong exposed port, service not bound, or server endpoint host misconfiguration
+- next actions: verify the port, inspect service logs, and if the endpoint host is unreachable from the client environment check the server endpoint configuration
+
+## Minimal Closed Loops
+
+CLI-first troubleshooting:
+
+```bash
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+osb devops summary <sandbox-id> -o raw
+osb devops events <sandbox-id> --limit 100 -o raw
+```
+
+Crash-focused investigation:
+
+```bash
+osb devops summary <sandbox-id> -o raw
+osb devops logs <sandbox-id> --tail 500 -o raw
+osb devops inspect <sandbox-id> -o raw
+```
+
+Endpoint troubleshooting:
+
+```bash
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
+osb sandbox endpoint <sandbox-id> --port <port> -o json
+osb devops logs <sandbox-id> --tail 200 -o raw
+```
+
+## Response Format
+
+Structure the answer in this order:
+
+1. current state: what the sandbox is doing now
+2. evidence: the command output that matters
+3. root cause: the most likely diagnosis, stated as confidence not certainty when needed
+4. next actions: specific fixes or follow-up checks
+
+Keep the conclusion compact.