📚 Docs

GitHub Copilot CLI

The web shell environment ships the GitHub Copilot CLI — the copilot command gives you AI-assisted suggestions, explanations, and chat right in the browser terminal.

Requirements: a GitHub account with an active Copilot plan (Free, Pro, Business, or Enterprise). If your GitHub account is managed by an organization, that organization must also enable its Copilot CLI policy. Each prompt consumes your plan's premium-request quota.

Signing in (one time per app)

There is no browser inside the container, so the CLI's default desktop web flow cannot complete here. Sign-in uses GitHub's device code flow instead — you finish it in a second browser tab:

  1. Open your web shell (see Web shell).

  2. Run the setup helper:

    ~/copilot-setup

    (equivalently: copilot login --device-code)

  3. The terminal prints a one-time code and a URL. Open https://github.com/login/device in a new browser tab, sign in to GitHub if asked, enter the code, and authorize.

  4. Back in the shell the CLI confirms the login. From now on just run:

    copilot

~/copilot-setup is safe to re-run any time: it detects an existing login (a stored token, not just the CLI's config file) or an operator-provided token and tells you when no sign-in is needed. Launching copilot first does not confuse it — quit the CLI and re-run the helper to sign in.

Staying signed in

There is no system keychain inside the container, so the CLI stores its OAuth token in plaintext in ~/.copilot/config.json (alongside the CLI's own metadata, which appears there on first launch). The file lives in the app container, so:

Operator: token-based auth instead of per-user login

An operator can give an app's sessions a GitHub token directly, so no interactive login is needed at all:

  1. Create a fine-grained personal access token owned by a personal GitHub account, with the Copilot Requests account permission. (Classic ghp_ tokens are not supported by the Copilot CLI.)

  2. Set it on the app:

    dokku config:set <app> COPILOT_GITHUB_TOKEN=github_pat_...

  3. Let web-shell sessions inherit it: on the Dokku host, allowlist the variable for the shell backend and restart it —

    printf '[Service]\nEnvironment="SHELL_ENV_ALLOWLIST=COPILOT_GITHUB_TOKEN"\n' \
  | sudo tee /etc/systemd/system/paas-shell-backend.service.d/copilot.conf
sudo systemctl daemon-reload
sudo systemctl restart paas-shell-backend

New sessions then start with COPILOT_GITHUB_TOKEN set and the CLI authenticates with it (credential precedence: COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN > stored OAuth login). Note this token is app-wide and visible to the operator — it is shared by every session of that app, exactly like a saved interactive login. dokku config:set restarts the app, which drops any active shell sessions of that app.

Operator: use Amazon Bedrock instead of GitHub models

When AWS credentials are present in a web-shell session, copilot runs through Bedrock's OpenAI-compatible endpoint (https://bedrock-runtime.<region>.amazonaws.com/openai/v1) with global.moonshotai.kimi-k3 as the default model, and GitHub sign-in is not needed. A short-lived bearer token is derived from the access key at every credential request by bin/bedrock-token (pure sh + openssl); it is never written to disk or logged.

Enable it by passing the credentials through to sessions: set them on the app and allowlist them for the shell backend (same mechanism as COPILOT_GITHUB_TOKEN above):

dokku config:set shell AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_REGION=eu-west-1
# backend drop-in, as in the token section:
#   Environment="SHELL_ENV_ALLOWLIST=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,AWS_REGION"

The IAM identity needs bedrock:CallWithBearerToken and model-invoke permissions. Region defaults to eu-west-1. Users can override the model with BEDROCK_MODEL=<id> copilot or copilot --model <id>, and the token lifetime with BEDROCK_TOKEN_TTL (seconds, default 3600). Use COPILOT_USE_GITHUB=1 copilot (or command copilot) for the GitHub-hosted CLI. Missing keys or a failed token derivation print a clear message and exit 1 before the CLI starts.

Troubleshooting