📚 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.

Build and deploy with built-in PaaS guidance

In the default shell app (https://shell.54.195.181.75.sslip.io/), the CLI starts with platform instructions in ~/.copilot/copilot-instructions.md and can load the bundled paas-deploy skill from ~/.copilot/skills/paas-deploy/SKILL.md. The skill covers building a self-contained app, connecting over the container's existing Dokku SSH identity, pushing to the master deploy branch, and checking the actual URL, logs and HTTP response. This works whether Copilot uses GitHub-hosted models or the Bedrock wrapper; no live documentation scrape or new service is needed.

After signing in (if required), try:

copilot
> Make me a small expense tracker and deploy it to a new app named expenses-demo.
> Add a health endpoint to my existing app and help me redeploy it.

The CLI should clarify only app-specific choices, confirm the target app, inspect it before updates, and explain what it is doing. You can view available skills with /skills. Inside this container the Dokku host is dokku: the CLI uses ssh dokku@dokku ... and pushes to dokku@dokku:<app> (for example git push dokku HEAD:master). Do not use host-only sudo dokku commands in this terminal.

Important limits:

For the platform contract and a manual walkthrough, see Application requirements and Deploy your first app.

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.

Keyless (recommended on EC2): if no AWS keys are in the session, bin/bedrock-token reads the instance role's credentials from IMDSv2 (hop limit 2 lets the container reach it). iam.tf grants the role dokku-bedrock-invoke (bedrock:InvokeModel*, CallWithBearerToken), and the metadata service is open to containers (block_container_imds = false, the default). Both are applied with terraform apply (no instance replacement); see app-container-hardening.md item 7 for the security trade-off. No env vars needed.

Alternative with static keys: pass 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