Skip to content

feat: add GitHub Codespaces provider#347

Open
coygeek wants to merge 18 commits into
openclaw:mainfrom
coygeek:feat/github-codespaces-provider
Open

feat: add GitHub Codespaces provider#347
coygeek wants to merge 18 commits into
openclaw:mainfrom
coygeek:feat/github-codespaces-provider

Conversation

@coygeek

@coygeek coygeek commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

Closes #348

Summary

Adds a direct GitHub Codespaces Linux SSH-lease provider with aliases codespaces and gh-codespaces.

  • Creates claim-owned GitHub Codespaces through the GitHub REST API and local gh authentication.
  • Uses gh codespace ssh --config to drive normal Crabbox SSH, rsync, run, ssh, status, stop, and cleanup flows.
  • Keeps the provider direct-only; it does not route through the Crabbox coordinator.
  • Adds provider config/flags/env handling, generated provider metadata, docs, OpenSSH config parsing, lifecycle tests, guarded standalone live-smoke coverage, and shared scripts/live-smoke.sh dispatch.
  • Keeps release and cleanup conservative: local claim required, creating login must match, dirty Codespaces fall back to stop/retain, and repo-local config cannot redirect creation to an arbitrary repository.

Verification

Local validation on current head 2eb4f8afe67f3072bea093d085795641290acc9c:

bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
node --test scripts/live-smoke.test.js scripts/live-github-codespaces-smoke.test.js
go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node scripts/check-docs-links.mjs
node scripts/check-command-docs.mjs
git diff --check

Earlier validation on the branch also covered provider matrix generation, go vet, deadcode, and go build after the rebase.

Public CI is green on current head: https://github.com/openclaw/crabbox/actions/runs/28098639697

Remaining Merge Gate

Do not merge yet while status: 📣 needs proof, merge-risk: 🚨 auth-provider, merge-risk: 🚨 compatibility, and merge-risk: 🚨 security-boundary remain. This still needs redacted authenticated GitHub Codespaces lifecycle proof:

CRABBOX_LIVE=1 \
CRABBOX_LIVE_PROVIDERS=github-codespaces \
CRABBOX_GITHUB_CODESPACES_SMOKE_REPO=<owner/repo> \
GH_TOKEN=<token> \
scripts/live-smoke.sh

Required proof should show doctor, create/wait for a short-lived Codespace lease, synced command execution, rendered SSH command, release/delete or safe stop/retain fallback, dry-run cleanup, final claim-owned inventory state, and no leaked token/output.

@clawsweeper

clawsweeper Bot commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 9:17 AM ET / 13:17 UTC.

Summary
Adds a built-in direct GitHub Codespaces SSH-lease provider with aliases, config/env/flags, REST and gh lifecycle code, docs, metadata, tests, and guarded live-smoke wiring.

Reproducibility: not applicable. this is a feature PR, not a bug report. The missing verification is merge-readiness proof for real GitHub Codespaces lifecycle behavior, not a current-main bug reproduction.

Review metrics: 3 noteworthy metrics.

  • Diff surface: 28 files changed, +4424/-4. This is a broad provider addition, so live proof and maintainer review matter beyond normal unit-test coverage.
  • Provider surface: 1 built-in SSH-lease provider added with 2 aliases. The provider name, aliases, and config keys become user-facing compatibility surface after release.
  • Live proof posted: 0 authenticated current-head runs. The PR body and maintainer comments still mark live Codespaces lifecycle proof as the merge gate.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #348
Summary: This PR is the open implementation candidate for the linked GitHub Codespaces provider feature request; the AWS Lambda MicroVM PR is adjacent provider-matrix history, not the same root cause.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Post redacted authenticated current-head lifecycle proof for doctor, warmup/create, status --wait, run, ssh command rendering, stop/delete or retain fallback, cleanup dry-run, and final inventory.
  • [P1] Keep private details redacted, including tokens, IP addresses, private repo endpoints, and non-public resource names where needed.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR body and maintainer comments say authenticated Codespaces lifecycle proof is still missing; the contributor should add redacted terminal output, logs, or a recording and update the PR body for re-review.

Risk before merge

  • [P2] No redacted authenticated live run has been posted for doctor, create/wait, status, synced run, SSH command generation, release/delete or retain fallback, cleanup dry-run, and final claim-owned inventory on the current head.
  • [P1] Merging adds a direct provider that uses the operator's GitHub CLI or token auth to create, stop, and delete billable remote resources, so identity, repository, token, and cleanup boundaries need explicit maintainer acceptance.
  • [P1] The provider name, aliases, config keys, environment variables, machine/work-root defaults, and delete/retain policy become compatibility surface once released.

Maintainer options:

  1. Post redacted live lifecycle proof (recommended)
    Run the documented CRABBOX_LIVE=1 Codespaces smoke against the current head and post redacted terminal output or logs showing the full create/status/run/ssh/release/cleanup path.
  2. Accept the provider contract explicitly
    Maintainers can decide that the provider name, aliases, defaults, direct-only mode, and delete/retain policy are the compatibility surface they want to support.
  3. Pause if no owner can prove it
    If no maintainer or contributor can supply authenticated Codespaces proof and own the provider contract, pause or close this PR until the provider can be sponsored safely.

Next step before merge

  • [P1] Human review remains because the blockers are live-provider proof and maintainer acceptance for the new built-in provider contract, not a narrow automated code repair.

Security
Needs attention: The diff introduces a GitHub-token-backed provider and remote resource mutation path, so security review should stay open until redacted live proof shows the credential and cleanup boundaries behave as intended.

Review details

Best possible solution:

Require redacted current-head live Codespaces lifecycle proof, then make an explicit maintainer call on whether this provider contract should ship as built-in core surface.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR, not a bug report. The missing verification is merge-readiness proof for real GitHub Codespaces lifecycle behavior, not a current-main bug reproduction.

Is this the best way to solve the issue?

Unclear until maintainers accept the product surface. The dedicated provider adapter matches the repository architecture if Crabbox wants this built in, but live proof and auth/security/compatibility acceptance are still required.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 73549f35a4a0.

Label changes

Label justifications:

  • P2: This is a normal-priority provider feature with clear value and limited blast radius, but it is not an urgent regression.
  • merge-risk: 🚨 auth-provider: The PR introduces GitHub CLI/token auth and provider routing for a new remote execution backend.
  • merge-risk: 🚨 compatibility: New provider names, aliases, config/env keys, defaults, and release policy become compatibility commitments once shipped.
  • merge-risk: 🚨 security-boundary: The provider sends GitHub credentials to an API endpoint and mutates claim-owned remote Codespaces, so credential and cleanup boundaries need proof.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body and maintainer comments say authenticated Codespaces lifecycle proof is still missing; the contributor should add redacted terminal output, logs, or a recording and update the PR body for re-review.
Evidence reviewed

Security concerns:

  • [medium] Needs live proof for GitHub token and cleanup boundaries — internal/providers/githubcodespaces/backend.go:494
    controlPlane reads GH_TOKEN/GITHUB_TOKEN or gh auth token and the client sends it as a bearer token for Codespaces lifecycle calls; this is intended, but it needs redacted live proof before merge.
    Confidence: 0.86

What I checked:

  • Repository policy read: AGENTS.md was read fully; its provider-boundary and no-secrets-on-argv guidance applies to this new direct-cloud provider. (AGENTS.md:1, 73549f35a4a0)
  • Current main lacks the provider: A current-main search only finds generic provider recommendation text for codespaces and no internal/providers/githubcodespaces implementation. (internal/cli/providers.go:558, 73549f35a4a0)
  • PR provider registration: The PR registers github-codespaces as a Linux SSH-lease provider with codespaces and gh-codespaces aliases and direct-only coordinator behavior. (internal/providers/githubcodespaces/provider.go:17, 2eb4f8afe67f)
  • Auth and lifecycle surface: The provider reads GH_TOKEN/GITHUB_TOKEN or gh auth token, constructs a REST client, creates Codespaces, generates SSH config, and deletes or stops claim-owned resources. (internal/providers/githubcodespaces/backend.go:485, 2eb4f8afe67f)
  • Untrusted config guard: The PR protects apiUrl, ghPath, and repo from untrusted repo-local config and adds a regression test for that redirect boundary. (internal/cli/config.go:4416, 2eb4f8afe67f)
  • Live proof still missing: The PR body and maintainer comments explicitly say not to merge yet because redacted authenticated Codespaces create/status/run/ssh/release proof is still required. (2eb4f8afe67f)

Likely related people:

  • coygeek: Current-main history shows recent provider foundation work by Coy Geek across Lambda, Firecracker, and Blaxel, and this PR/linked issue continue that provider area. (role: recent provider contributor and linked implementation owner; confidence: high; commits: 6e7939dbdc63, 3f72d94e2ae7, a90b7807a9a0; files: internal/cli/config.go, internal/providers/all/all.go, internal/providers/githubcodespaces)
  • vincentkoc: Vincent Koc recently maintained live-smoke dispatch on current main and pushed the PR rebase/shared smoke wiring commits called out in the review discussion. (role: recent live-smoke and branch maintenance contributor; confidence: high; commits: 56d058c0b846, ee77a6523196, 2eb4f8afe67f; files: scripts/live-smoke.sh, scripts/live-github-codespaces-smoke.sh, docs/providers/README.md)
  • steipete: The current PR was rebased over the merged AWS Lambda MicroVM provider work, which touched the same provider registry, docs matrix, and direct-provider surface. (role: recent adjacent provider contributor; confidence: medium; commits: 0301236b2752; files: internal/providers/all/all.go, docs/providers/README.md, docs/providers/provider-metadata.json)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@coygeek coygeek marked this pull request as ready for review June 14, 2026 07:10
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. merge-risk: 🚨 auth-provider 🚨 Merging this PR could break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 security-boundary 🚨 Merging this PR could weaken sandboxing, authorization, credentials, or sensitive data. labels Jun 14, 2026
@vincentkoc vincentkoc force-pushed the feat/github-codespaces-provider branch from 1887b52 to 2afc239 Compare June 24, 2026 05:32
@vincentkoc

Copy link
Copy Markdown
Member

@clawsweeper re-review

Maintainer update on 2afc239e021e093fd021e2b09657d7831e7cb0ba:

  • rebased the GitHub Codespaces provider branch onto current main
  • fixed the CI Go/deadcode failure by removing unreachable helper wrappers from internal/providers/githubcodespaces/core.go
  • regenerated the provider category matrix so the generated docs check stays in sync

Local validation:

go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox

GitHub CI on the pushed head is green: Go, Apple VZ, Worker, Scripts, Docs, and Release Check all passed in https://github.com/openclaw/crabbox/actions/runs/28077485642.

Still not merging this yet: it remains gated by status: 📣 needs proof, merge-risk: 🚨 auth-provider, merge-risk: 🚨 compatibility, and merge-risk: 🚨 security-boundary. I do not have live GitHub Codespaces provider credentials/quota proof here, so this still needs real live create/status/run/ssh/release evidence before merge readiness.

@clawsweeper

clawsweeper Bot commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

coygeek and others added 17 commits June 24, 2026 16:55
Add the discoverable github-codespaces provider foundation with typed config, provider flags, redaction-safe client and gh runner boundaries, and OpenSSH config parsing for the future SSH lease lifecycle.

Keep live Codespaces lifecycle behavior intentionally deferred to the next plan while making doctor fail closed until readiness is implemented.
Add claim-backed acquire, resolve, list, release, touch, cleanup, and doctor behavior for GitHub Codespaces, including generated OpenSSH config targets and conservative delete safety checks.

Release and cleanup mutations now require local ownership claims, refuse dirty or unpushed codespaces before delete, and keep retained lease labels/endpoints consistent across stop and wake flows.

Verification: go test ./internal/providers/githubcodespaces; go test -race ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli
Document the direct GitHub Codespaces provider, add generated matrix metadata, and add a guarded live smoke with deterministic gating/redaction tests.
Align the GitHub Codespaces backend with the documented default cleanup policy, GitHub CLI token precedence, bounded provisioning waits, explicit generic work root handling, and the real gh SSH config Host alias shape.
Validate that the guarded GitHub Codespaces smoke lease is absent after cleanup without failing on unrelated retained claim-owned Codespaces leases.
Persist the effective Codespaces work root into lease labels and claims, and rewrite generated gh SSH proxy commands to honor the configured GitHub CLI path.
Keep GitHub Codespaces display names within the documented limit for long but valid Crabbox slugs while preserving the collision-resistant suffix. Also assert that create requests continue using the current geo field rather than the legacy location field.
Fall back to stopping and retaining a Codespace when default delete-on-release is unsafe because the remote worktree has uncommitted or unpushed changes. This avoids turning successful runs into failed cleanup while still clearing stale SSH endpoints.
Make the release-claim retention hook read the post-release claim state so dirty Codespaces that fall back from delete to stop are not orphaned by higher-level release finalizers.
Treat GitHub Codespaces 304 Not Modified start responses as successful no-ops so resolving retained Codespaces can continue polling the existing codespace.
Apply the generic --type machine override for the canonical provider and advertised Codespaces aliases so alias-based invocations do not silently provision the default machine size.
Treat GitHub Codespaces 304 Not Modified delete responses as successful no-ops so release and cleanup remain idempotent when GitHub reports no remote state change is needed.
Allow StatusOnly resolves with ReadyProbe to refresh and probe the SSH target so status --wait can observe readiness for healthy Codespaces leases.
Warmup keep semantics should keep a lease available after provisioning, not rewrite the later provider release action. Preserve the delete-on-release policy in stored Codespaces claims so default stop and cleanup paths delete claim-owned Codespaces unless configuration explicitly retains them.
Treat githubCodespaces.repo like the other Codespaces connection selectors when loading untrusted repository config. Repo-local config can no longer redirect creation to an arbitrary repository; operators can still select a repo through trusted config, environment, or explicit CLI flags.
@vincentkoc vincentkoc force-pushed the feat/github-codespaces-provider branch from 2afc239 to 41ccc44 Compare June 24, 2026 08:58
@vincentkoc

Copy link
Copy Markdown
Member

Rebased this PR onto current main after #674 landed.

New head: 41ccc44ed02061a53eb20a55a848ed18aa91f352

Conflict resolution kept both AWS Lambda MicroVM and GitHub Codespaces in generated docs/source-map metadata. Provider matrix now reports 67 providers.

Local validation on the rebased head:

go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node --test scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox
git diff --check

Still not merging: live GitHub Codespaces create/status/run/ssh/release proof and auth/security/compatibility gates are still required.

@vincentkoc

Copy link
Copy Markdown
Member

Public CI is green on rebased head 41ccc44ed02061a53eb20a55a848ed18aa91f352: https://github.com/openclaw/crabbox/actions/runs/28087205563

Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check. Merge state is clean.

Still not merging: status: 📣 needs proof plus auth-provider/compatibility/security-boundary labels remain, and this still needs redacted live GitHub Codespaces create/status/run/ssh/release proof.

@vincentkoc

Copy link
Copy Markdown
Member

Maintainer proof update for github-codespaces shared live-smoke wiring.

Changed:

  • wired CRABBOX_LIVE_PROVIDERS=github-codespaces|codespaces|gh-codespaces through scripts/live-smoke.sh to the guarded standalone Codespaces smoke
  • added shared dispatch regression coverage that proves the shared smoke exits before provider mutation when the smoke repo is missing
  • documented the shared operations entry point and provider prerequisites

Local validation at head 2eb4f8af:

  • bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
  • node --test scripts/live-smoke.test.js scripts/live-github-codespaces-smoke.test.js
  • go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
  • node scripts/check-docs-links.mjs
  • node scripts/check-command-docs.mjs
  • git diff --check

Still not claiming live provider proof from this machine because I do not have an authenticated Codespaces smoke repo/token here. The added path is meant to make that live proof one standard command once credentials are available.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@vincentkoc

Copy link
Copy Markdown
Member

Public CI is now green on current head 2eb4f8afe67f3072bea093d085795641290acc9c: https://github.com/openclaw/crabbox/actions/runs/28098639697.

Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check.

Still not merging: authenticated GitHub Codespaces lifecycle proof remains missing, and status: 📣 needs proof plus auth/compat/security risk labels remain.

@vincentkoc

Copy link
Copy Markdown
Member

@clawsweeper re-review

Updated the PR body with current-head validation evidence, full issue link, and the remaining authenticated live-proof gate. No code changes in this update.

Still not merging unless the live Codespaces proof labels clear and the auth/compat/security gates are satisfied.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 auth-provider 🚨 Merging this PR could break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. merge-risk: 🚨 security-boundary 🚨 Merging this PR could weaken sandboxing, authorization, credentials, or sensitive data. P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add GitHub Codespaces as a Crabbox Linux provider

2 participants