Launch Openshell Gator

Launch OpenShell Gator

Launch and supervise the repository's headless gator sandbox agent through OpenShell. This skill covers the operator workflow around scripts/agents/run.sh; the in-sandbox review and state-machine policy remains the gator-gate skill baked into the gator payload.

For gator's PR/issue validation policy, load gator-gate inside the launched sandbox. For generic sandbox CLI usage, use openshell-cli. For unhealthy gateways or sandbox startup failures, use debug-openshell-cluster after the launch preflight identifies a gateway/runtime problem.

Non-Negotiable Rules

• Keep normal gator launches supervised: use --watch and let the in-sandbox supervisor own sleeping and relaunching bounded cycles.
• Do not add passive sleep loops in the operator session to watch gator. Check logs or status once, then report the current state or launch a proper watcher outside the model session only when explicitly asked.
• Do not change the default gator model in scripts/agents/gator/agent.yaml for experiments. Use CODEX_MODEL=... and, if needed, a temporary --from Docker context or --codex-bin override.
• Do not push to contributor branches, approve, merge, post /ok to test, or broaden gator scope unless the operator explicitly authorized that action.
• Scope each launch prompt to the requested issue/PR set. Avoid repo-wide gator scans unless the operator asked for repo-wide processing.
• Leave unrelated local files alone, including .opencode/ artifacts and old gator logs unless the user asks for cleanup.

Key Paths

Preflight

Run these checks before launching unless the operator asks for a best-effort launch.

Step 1: Confirm Repository Root

git rev-parse --show-toplevel
git status --short --branch

Use the repository root as the working directory for all commands. A dirty worktree is allowed, but do not stage or modify unrelated files.

Step 2: Verify Required Host Tools

command -v openshell
command -v gh
command -v jq
command -v ruby

The local openshell wrapper may recompile the CLI. If that fails, fix the local build or ask the operator before changing unrelated source.

Step 3: Verify GitHub Auth

Use gh api user as the health check. It works with provider-scoped tokens and matches gator's own auth guidance.

gh api user --jq '.login'
gh api repos/NVIDIA/OpenShell --jq '{full_name,default_branch}'

If this fails, refresh host gh auth before launching. Do not rely on gh auth status alone inside provider-backed sandboxes.

Step 4: Verify Codex Auth For Codex Harness

The default gator harness is Codex. Check that the host has usable Codex auth material:

jq -e '.tokens.access_token and .tokens.refresh_token and .tokens.account_id' "$HOME/.codex/auth.json" >/dev/null

If this fails, run the local Codex login flow outside the gator launch. If Codex was recently reauthenticated and gateway refresh fails later, relaunch with --reset-refresh once.

The launcher passes the non-secret host account ID as literal CODEX_ACCOUNT_ID for Codex's local workspace routing. The harness must not use the opaque CODEX_AUTH_ACCOUNT_ID credential placeholder for that comparison. Access tokens remain placeholders, and refresh material remains gateway-only.

Step 5: Verify Gateway Is Registered And Alive

Use the target gateway from the operator request or current session context. Do not assume a gateway name. If the operator did not specify one, list registered gateways and ask before launching when the correct target is ambiguous.

openshell gateway list

gateway_name="<selected-gateway-name>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }

openshell --gateway "$gateway_name" status
openshell --gateway "$gateway_name" sandbox list

Expected result: status returns successfully and sandbox listing completes. If the gateway is unreachable, the runtime cannot create sandboxes, or sandbox listing hangs, switch to debug-openshell-cluster and fix the gateway before launching gator.

Step 6: Check Existing Gator Sandboxes

Avoid duplicate gators for the same PR unless intentionally replacing a stuck or stale one.

gateway_name="<selected-gateway-name>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }

openshell --gateway "$gateway_name" sandbox list

Look for names like gator-pr-<number>-supervised. If one exists, inspect its log before deleting or relaunching.

Input Normalization

Never paste raw operator text into shell arguments such as --gateway, --name, --from, issue numbers, or PR numbers. Normalize values before constructing launch commands.

Use the operator-specified gateway or a gateway selected from openshell gateway list:

gateway_name="<selected-gateway-name>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }

Use digits only for issue and PR numbers:

pr_number="<digits-only>"
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }

Use the portable Kubernetes DNS-1123 sandbox-name format even when the selected gateway currently uses another driver:

sandbox_name="gator-pr-${pr_number}-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

For local image contexts passed to --from, use an agent-created path such as mktemp -d; do not pass raw user-supplied paths without validating that they are expected local Dockerfile contexts.

Standard Launches

Launch A PR Watcher

Use a stable, scoped name and a prompt that names exactly what gator should do.

gateway_name="<selected-gateway-name>"
pr_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
sandbox_name="gator-pr-${pr_number}-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --watch \
  "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}."

The launcher queries the gateway's selected compute driver, builds the gator image in the matching Docker or Podman image store, stages the immutable payload, imports provider profiles, configures provider credentials and refresh, and starts the agent supervisor as the sandbox's canonical main process. The detached main process survives loss of the host CLI connection and reconnects to a restarted gateway. Unless --keep is set, the sandbox is marked ephemeral so the gateway deletes it after the canonical main process exits and its terminal result is finalized. CONTAINER_ENGINE, when set, must match the gateway driver.

The launcher streams image-build and provisioning output until the detached workload is ready, then exits. Use openshell logs <sandbox-name> or the TUI for runtime output.

Launch An Issue Or Issue/PR Pair

gateway_name="<selected-gateway-name>"
issue_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; }
sandbox_name="gator-issue-${issue_number}-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --watch \
  "Run gator on issue #${issue_number}. Scope this invocation only to issue #${issue_number}."

For a linked pair:

gateway_name="<selected-gateway-name>"
pr_number="<digits-only>"
issue_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; }
sandbox_name="gator-pr-${pr_number}-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --watch \
  "Review and monitor PR #${pr_number} with linked issue #${issue_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number} and issue #${issue_number}."

Launch With Explicit Maintainer Authorization

Only include authorization in the prompt when the operator explicitly gave it.

gateway_name="<selected-gateway-name>"
pr_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
sandbox_name="gator-pr-${pr_number}-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --watch \
  "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}. The operator explicitly authorizes applying the test:e2e label, posting /ok to test with the full 40-character current head SHA, and rerunning the relevant current-head workflow when the E2E Label Help bot says that is required."

Model Or Image Experiments

Use environment overrides. Do not edit agent.yaml for temporary experiments.

gateway_name="<selected-gateway-name>"
pr_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }

CODEX_MODEL=gpt-5.6-sol \
./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --watch \
  "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}. This launch is intentionally testing Codex model gpt-5.6-sol via the CLI launcher."

If the installed Codex CLI is too old for a model, create a temporary copy of scripts/agents/gator/, adjust only that temporary Dockerfile, and launch with that generated context. Keep the repo Dockerfile unchanged unless the version bump is the intended code change.

Example shape:

gateway_name="<selected-gateway-name>"
pr_number="<digits-only>"
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised"
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
tmp_context="$(mktemp -d "${TMPDIR:-/tmp}/gator-codex-XXXXXX")"
cp -R scripts/agents/gator/. "$tmp_context"/

CODEX_MODEL=gpt-5.6-sol \
./scripts/agents/run.sh \
  --agent gator \
  --gateway "$gateway_name" \
  --name "$sandbox_name" \
  --from "$tmp_context" \
  --watch \
  "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}."

Monitoring

Read The Launch Result

The launcher streams image-build and provisioning output to the terminal. Important markers:

• Built image ... means the local image build completed.
• Created sandbox: <name> means OpenShell accepted the sandbox.
• openshell-agent: starting watch cycle means the in-sandbox supervisor began a bounded cycle.
• OpenAI Codex v... plus model: ... confirms the Codex CLI and model actually used.
• OPENSHELL_AGENT_RESULT {...} is the bounded-cycle sentinel. In watch mode, the supervisor sleeps and relaunches after this line.
• /sandbox/.openshell-agent/status.json is the atomic current state snapshot. Its result.notes field is Gator's plain-language diagnosis and next action for that cycle.
• /sandbox/.openshell-agent/history.jsonl contains the latest 100 supervisor transitions, including active-cycle starts and completed cycle results.
• openshell-agent: still running watch cycle ... is a heartbeat during long active model cycles.
• review_feedback_lookup_failed means Gator could not build the required cross-SHA feedback ledger and deliberately skipped a context-free review.