webgh

webgh connects a machine to the Copilot Session Portal so its GitHub Copilot CLI sessions can be created and controlled from the web.

Install and run

Prerequisites:

• Node.js 20 or newer
• Git
• GitHub CLI authenticated with gh auth login
• GitHub Copilot CLI installed and authenticated with copilot login

npm install --global @andrewhobden/webgh
webgh

If npm is unavailable or a Codespace routes it through an inaccessible private feed, install the portable core CLI without npm:

curl -fsSL https://copilot-cli.dev/install-webgh.sh | sh
export PATH="$HOME/.local/bin:$PATH"
webgh

The portable executable supports core session, team, file, and Git operations. Remote terminals and the embedded browser require the full npm package because they depend on node-pty and Playwright.

With no arguments, webgh connects to wss://copilot-cli.dev and stores sessions in ~/.copilot-session-portal/sessions. The host runs in the foreground and reconnects automatically if the portal is temporarily unavailable.

Link an existing repository

In the portal, choose New session or New agent team → Existing repository, select the host, and enter an absolute path to a Git worktree. WebGH uses the repository in place and stores its metadata centrally under the configured sessions root; it does not add .portal files or change .gitignore in the linked repository.

For a linked team, the repository's checked-out branch becomes the team base. Adding team members necessarily creates Git worktrees and agent/* branches in the repository's Git metadata. Those member directories remain under the configured sessions root.

Linked workspaces have deliberately safer lifecycle rules:

• Unlink removes only the portal registration, never repository files.
• Rename changes only the portal display name.
• Duplicate creates a fresh managed copy under the sessions root with new Git history.
• Move to host is unavailable until the repository is duplicated/imported into managed storage.

If a linked path is unmounted or moved, it remains visible as unavailable. For a session, choose Relink and provide its new absolute path to preserve the same Copilot conversation. A team can be unlinked and added again after its path returns. Symlinks and paths inside a worktree are normalized to the canonical Git top-level directory.

Run diagnostics or install optional Chromium support for the portal's embedded browser:

webgh doctor
webgh setup

webgh setup --skip-browser creates the state directory without downloading Chromium. A missing browser never prevents the host itself from starting.

Configuration

Command-line options override environment variables and .env; defaults apply last.

| Option | Environment | Default | | --- | --- | --- | | --backend-url <url> | BACKEND_URL | wss://copilot-cli.dev | | --sessions-root <path> | SESSIONS_ROOT | ~/.copilot-session-portal/sessions | | --host-name <name> | HOST_NAME | Machine hostname | | --copilot-bin <path> | COPILOT_BIN | copilot | | — | HOST_ID | Persisted under the sessions root | | — | GITHUB_TOKEN | Current gh auth token | | — | TERMINAL_SHELL | Login shell or PowerShell |

Browser tuning is available through BROWSER_ALLOWED_PORTS, BROWSER_MAX_WIDTH, BROWSER_MAX_HEIGHT, BROWSER_FRAME_QUALITY, BROWSER_MAX_FPS, and BROWSER_HEADLESS. When BROWSER_ALLOWED_PORTS is set, it applies to typed URLs, links, and redirects; include 80 and 443 to allow standard web browsing.

To connect to a development or self-hosted backend:

webgh --backend-url ws://localhost:8080 --sessions-root ./sessions

Do not pass tokens on the command line. Use gh auth login or an environment variable supplied by your secret manager.

Background operation

webgh intentionally does not install an operating-system service. Run the same foreground command under your preferred manager:

• Linux: a systemd user service with ExecStart=/path/to/webgh.
• macOS: a LaunchAgent whose ProgramArguments contains the absolute webgh path.
• Windows: a service wrapper such as WinSW or NSSM invoking webgh.cmd.

Use absolute executable and sessions-root paths because service managers often have a restricted PATH and a different working directory. Provide credentials through the service manager's protected environment.

Troubleshooting

• Run webgh doctor first; webgh doctor --json is available for automation.
• No GitHub identity: run gh auth login.
• Copilot unavailable: install the Copilot CLI and run copilot login.
• Embedded browser unavailable: run webgh setup.
• Native terminal unavailable: reinstall webgh so node-pty can install the correct platform binary.

Security

The portal can run Copilot with all tools, open terminals, browse HTTP(S) URLs using this host's network access, and configure MCP servers on this host. Only connect hosts you control to a trusted portal. Host authentication uses the local GitHub identity and tokens are never persisted by webgh.

License: MIT.

Maintainer release

Trusted publishers can only be attached after an npm package exists. For the first 0.1.0 release, authenticate the maintainer machine with npm, run pnpm test:package, pack from the workspace, and publish that exact tarball manually with --access public. Do not create the release tag first. This one-time bootstrap release cannot carry trusted-publisher provenance.

After the package exists, configure npm trusted publishing for this repository's .github/workflows/webgh-release.yml workflow and the npm GitHub environment. Subsequent releases use a tag matching the package version exactly, such as webgh-v0.1.1; the workflow rebuilds and validates the tarball before publishing it with provenance. No long-lived npm token is stored.