Skip to content

feat(portless): register vnc-<box>.localhost alias for every box#9

Merged
madarco merged 1 commit into
mainfrom
feat/vnc-portless-alias
May 27, 2026
Merged

feat(portless): register vnc-<box>.localhost alias for every box#9
madarco merged 1 commit into
mainfrom
feat/vnc-portless-alias

Conversation

@madarco
Copy link
Copy Markdown
Owner

@madarco madarco commented May 27, 2026

Summary

  • Mints a second Portless alias per box at create time alongside the existing <box>.localhost web alias: vnc-<box>.localhost points at the noVNC port (container 6080 on docker, the SSH-forwarded local port on Hetzner). Gives the user a stable URL for the noVNC viewer instead of a random ephemeral loopback port that re-rolls on every stop/start.
  • Wired uniformly across docker, daytona, and hetzner. Naturally no-ops on backends whose previewUrl() isn't loopback (Daytona), mirroring the existing web alias. Re-registered on start (host port reallocation) and dropped on destroy.
  • agentbox screen and agentbox inspect now prefer the new URL on non-OrbStack engines; agentbox url grew a --kind <web|vnc> flag.

Test plan

  • pnpm typecheck clean
  • pnpm test — all 515 tests green (5 new for the VNC URL preference matrix in endpoints.test.ts, 1 state round-trip case)
  • Docker e2e on Docker Desktop:
    • agentbox create -y --portless registers both <box>.localhost and vnc-<box>.localhost (visible in create.log)
    • curl https://vnc-<box>.localhost/vnc.html -k returns 200 (noVNC loads)
    • agentbox screen <box> --print returns the Portless URL with ?autoconnect=1&password=…
    • agentbox url <box> --kind vnc --print returns https://vnc-<box>.localhost
    • agentbox stop && agentbox start re-registers after host port re-rolls; noVNC still serves 200
    • agentbox destroy -y removes both routes from ~/.portless/routes.json
  • Hetzner e2e (deferred — needs a fresh agentbox prepare --provider hetzner; logic mirrors docker, gated on the same --portless opt-in)
  • Daytona graceful skip (deferred — verified by inspection: parseLoopbackPort returns undefined for Daytona's signed preview URL, same as today's web path)

Note

Low Risk
Best-effort Portless registration with existing fallbacks; no auth or data-model breaking changes beyond new optional record fields.

Overview
Adds a second Portless alias per boxvnc-<name>.localhost → the noVNC port — alongside the existing web alias, persisted on BoxRecord as portlessVncAlias / portlessVncUrl. Docker registers it at create; cloud (Hetzner loopback previews) registers at create/start via a shared registerHostPortlessAlias helper; both aliases are re-pointed after start when host ports change and removed on destroy.

CLI / UX: agentbox url gains --kind web|vnc (with VNC guards). agentbox screen and Docker getBoxEndpoints now prefer Portless → OrbStack → loopback for VNC on non-OrbStack engines (stable URL across restarts). Cloud resolveUrl and list/inspect surfaces include Portless VNC when present.

Tests: State round-trip and endpoint preference matrix for VNC Portless URLs.

Reviewed by Cursor Bugbot for commit c99ec63. Configure here.

Mints a second Portless alias per box at create time alongside the
existing `<box>.localhost` web alias, pointing at the noVNC port. Gives
the user a stable, memorable URL for the VNC viewer instead of a random
loopback port that re-rolls on every stop/start.

Wired uniformly across docker, daytona, and hetzner — naturally no-ops
on backends whose `previewUrl()` isn't loopback (Daytona), same as the
existing web alias. Re-registers on `start` (host port can change) and
drops both aliases on `destroy`.

Reuses `portlessAlias` / `portlessUnalias` from `@agentbox/sandbox-docker`
and `parseLoopbackPort` from `@agentbox/sandbox-cloud`; no new helpers
beyond a small `registerHostPortlessAlias` extraction in the cloud
provider. Adds `--kind <web|vnc>` to `agentbox url` and makes
`agentbox screen` + `agentbox inspect` prefer the new URL.
@madarco madarco force-pushed the feat/vnc-portless-alias branch from c99ec63 to fcafdc9 Compare May 27, 2026 20:19
@madarco madarco merged commit d5dedd5 into main May 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant