docs(agents): add gator launch skill by johntmyers · Pull Request #2203 · NVIDIA/OpenShell

johntmyers · 2026-07-09T18:22:06Z

Summary

Add a main repository skill for launching and supervising OpenShell gator agents through scripts/agents/run.sh.

Related Issue

N/A

Changes

Added .agents/skills/launch-openshell-gator/SKILL.md with preflight, launch, monitoring, restart, and troubleshooting workflows.
Documented the skill in the CONTRIBUTING.md agent skills inventory.

Testing

git diff --check passes
mise run pre-commit passes
Unit tests added/updated (not applicable)
E2E tests added/updated (not applicable)

Checklist

Follows Conventional Commits
Commits are signed off (DCO)

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

pimlock

🚢

Couple of nits, around how this skill would be included in the context.

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

drew

lgtm

drew · 2026-07-10T03:04:20Z

gator-agent

PR Review Status

Validation: This is a concentrated repository documentation/agent-skill update for launching supervised OpenShell gator agents, so it is project-valid.
Head SHA: 5427f87a50ed877049a44e6b28d24936dd107925

Thanks @pimlock, I checked the trigger-scope and intro concerns you raised. The latest commits removed the broad gateway/model trigger wording and trimmed the extra intro, so that feedback appears addressed.

Review findings:

.agents/skills/launch-openshell-gator/SKILL.md:108 and .agents/skills/launch-openshell-gator/SKILL.md:233: the skill shows commands where agents substitute PR/issue/sandbox placeholders directly into shell arguments. Please add an explicit guardrail to normalize PR/issue IDs to digits only and sandbox names to a safe character set such as [A-Za-z0-9_.-]+, and to avoid pasting raw operator text into --name, --from, or numeric placeholders. This avoids command/argument injection risk in the operator workflow.
.agents/skills/launch-openshell-gator/SKILL.md:173 and .agents/skills/launch-openshell-gator/SKILL.md:183: the model/image experiment example uses a hard-coded host-specific temp path. Please switch this to a portable generated temp directory, for example tmp_context="$(mktemp -d "${TMPDIR:-/tmp}/gator-codex-XXXXXX")", and pass that path to --from.

Docs: No Fern docs navigation update is needed because this does not change user-facing CLI/API behavior.

Next state: gator:in-review

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

elezar · 2026-07-10T15:48:19Z

+
+- Keep normal gator launches supervised: use `--watch --background` 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 use `--keep` for normal supervised gators. The launcher already keeps watch-mode sandboxes alive through the supervisor.


nit: I thought that --keep was deprecated / the default. Does that mean that one needs to specify --no-keep explicitly?

Yes, it was deprecated a while ago and just got removed (#2126).

If the intention is for the sandbox to be deleted when the command exits, the --no-keep should be used.

elezar · 2026-07-10T15:49:38Z

+- 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.
+- Treat `/etc/openshell/agent-payload` as immutable once a sandbox is created. After prompt/skill/runtime/image changes, delete and relaunch the affected gator instead of trying to patch files in-place.


Is this something that can be enforced through a policy?

I don't think we even need this statement. I've been able to adjust a running agent by just pushing updated skills, etc if I want to update it while it's running. I don't think there's a reason for it to treat it as immutable.

OK. If we don't think there's a reason to enforce it, then let's drop it.

elezar · 2026-07-10T15:51:12Z

+
+### Step 5: Verify Gateway Is Registered And Alive
+
+Use the target gateway, usually `docker-dev` for local gators.


Note: If the user is using an installed openshell, I think this is openshell and not docker-dev.

good call. removing all the hard coded docker-dev refs so it can be dynamic

elezar · 2026-07-10T15:52:20Z

+openshell --gateway docker-dev sandbox list
+```
+
+Look for names like `gator-pr-<number>-supervised`. If one exists, inspect its log before deleting or relaunching.


When I was using this, my gator sandboxes were something like gator-<TIMESTAMP. There was no PR reference. How do we handle those "conflicts"?

Later in this skill we have issue-specific sandbox names. Should those be checked for conflicts too?

I would imagine you could steer that w/ the local agent using the skill right and it's going to depend on how the local agent names sandboxes or if you want to direct it to a different naming convention. Nothing in a skill is authoritative.

Maybe as a follow up: What's the "worst" that can happen if multiple agents are looking at the same PR/issue? Their per-sha state is local, correct.

elezar · 2026-07-10T15:53:46Z

+```bash
+issue_number="<digits-only>"
+[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; }
+sandbox_name="gator-issue-${issue_number}-supervised"


Are we concerned about conflicts for these too?

elezar · 2026-07-10T15:56:51Z

+  --from "$tmp_context" \
+  --watch \
+  --background \
+  "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}."


Question: Should the "scope this invocation only to PR ... " be the default?

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

docs(agents): add gator launch skill

aa88bd8

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers requested review from a team, derekwaynecarr, maxamillion and mrunalp as code owners July 9, 2026 18:22

pimlock previously approved these changes Jul 9, 2026

View reviewed changes

Comment thread .agents/skills/launch-openshell-gator/SKILL.md Outdated

Comment thread .agents/skills/launch-openshell-gator/SKILL.md Outdated

docs(agents): narrow gator launch trigger

2c303e0

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers dismissed pimlock’s stale review via 2c303e0 July 9, 2026 21:38

pimlock previously approved these changes Jul 9, 2026

View reviewed changes

docs(agents): trim gator launch skill intro

5427f87

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers dismissed pimlock’s stale review via 5427f87 July 10, 2026 00:16

johntmyers requested a review from pimlock July 10, 2026 00:21

pimlock previously approved these changes Jul 10, 2026

View reviewed changes

drew added gator:in-review Gator is reviewing or awaiting PR review feedback and removed gator:in-review Gator is reviewing or awaiting PR review feedback labels Jul 10, 2026

drew previously approved these changes Jul 10, 2026

View reviewed changes

drew added the gator:in-review Gator is reviewing or awaiting PR review feedback label Jul 10, 2026

docs(agents): harden gator launch examples

12ecf38

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers dismissed stale reviews from drew and pimlock via 12ecf38 July 10, 2026 15:46

elezar reviewed Jul 10, 2026

View reviewed changes

docs(agents): avoid assuming gator gateway

3475f24

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>


		### Step 5: Verify Gateway Is Registered And Alive

		Use the target gateway, usually `docker-dev` for local gators.

Uh oh!

Conversation

johntmyers commented Jul 9, 2026

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

pimlock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

drew left a comment

Choose a reason for hiding this comment

Uh oh!

drew commented Jul 10, 2026

PR Review Status

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elezar Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

elezar Jul 10, 2026 •

edited

Loading