Skip to main content
GitHub Copilot CLI is GitHub’s terminal coding agent. Run it in a Superserve sandbox so its shell commands and file edits stay isolated from your machine. Copilot CLI can use models from a GitHub Copilot subscription, or a model provider key that you bring yourself. This page uses an Anthropic API key, which needs no GitHub account. To use your Copilot subscription instead, see Use a GitHub Copilot subscription.

Via the console

  1. On the Secrets page, create a secret with the Anthropic provider and paste your API key — you only do this once, and the key never enters the sandbox.
  2. Go to console.superserve.ai and click Create sandbox.
  3. Pick the superserve/node-22 template.
  4. Under Advanced Options → Secrets, bind that secret to COPILOT_PROVIDER_API_KEY.
  5. Under Advanced Options → Environment Variables, add COPILOT_PROVIDER_TYPE = anthropic, COPILOT_PROVIDER_BASE_URL = https://api.anthropic.com, and COPILOT_MODEL = claude-sonnet-4-6.
  6. Create the sandbox, open its Terminal, and run:

Via the SDK

When COPILOT_PROVIDER_BASE_URL is set, Copilot CLI sends model requests to that provider instead of GitHub, and it doesn’t ask you to sign in. COPILOT_MODEL selects the model. Copilot CLI reads the key from COPILOT_PROVIDER_API_KEY, but its value is a stand-in token — the real key is attached only on requests to Anthropic, never exposed to the agent. Open the sandbox in the console, launch the terminal, and run copilot. On the first start, Copilot CLI asks whether you trust the files in the current folder.

Use an OpenAI key

To use an OpenAI model, create the secret with the OpenAI provider and point Copilot CLI at the OpenAI API. COPILOT_PROVIDER_TYPE defaults to openai, so you can leave it out. Set COPILOT_PROVIDER_WIRE_API to responses for GPT-5 series models.
Install Copilot CLI in this sandbox as shown above, then use openaiSandbox (openai_sandbox in Python) in place of sandbox in the examples below. Run copilot help providers-env in the sandbox for every provider setting, including Azure OpenAI and other OpenAI-compatible endpoints.

Run headless

Pass a prompt with -p. Copilot CLI runs it in the sandbox, prints its final answer and a usage summary, and exits. A headless run can’t ask for approval, so it denies every tool that no allow rule covers. Add --allow-all-tools so the agent runs shell commands and edits files without stopping. An agent run can take several minutes. Pass output callbacks to each run() that starts the agent: a streamed run() gets keepalive messages while the agent works, so the connection stays open. A run() without callbacks gets no response until the command ends, and in TypeScript on Node.js it fails after 300 seconds, even with a longer timeoutMs. See Streaming output.
Add -s to print only the agent’s answer, without the usage summary. To allow less than every tool, replace --allow-all-tools with rules such as --allow-tool='write' --allow-tool='shell(npm:*)', and block commands with --deny-tool='shell(git push)'. Deny rules win over every allow rule. Run copilot help permissions for the rule syntax.
Auto-approved commands stay inside the sandbox and can’t touch your machine, but the sandbox can still reach the internet. Use network rules to limit where it can connect. With a provider key, Copilot CLI needs only your provider’s API host, for example api.anthropic.com, plus registry.npmjs.org if you install it after you restrict the network. If you deny all other traffic, also allow the sandbox’s DNS resolvers, 1.1.1.1/32 and 8.8.8.8/32, so these names resolve.

Get JSON output

Use --output-format json to get one JSON event per line. Each assistant.message event holds a message from the agent in data.content, and the last one holds its final answer. The last line is a result event with the session ID in sessionId and the run’s exit code in exitCode. If the run fails, for example because the key is not valid, Copilot CLI exits with a non-zero code, and a session.error event holds the message in data.message. These runs pass only a stderr callback, so the events on stdout aren’t printed while they arrive. The callback still keeps the connection open, and result.stdout holds every event when the run ends.
Other events report tool calls (tool.execution_start, tool.execution_complete) and streamed text (assistant.message_delta).

Continue a session

Copilot CLI saves each run as a session in ~/.copilot. Pass the session ID to --resume to send a follow-up with the earlier context, or use --continue to resume the most recent session.

Work on a repository

Clone a repository into the sandbox, stream Copilot CLI’s output while it works, then read the diff.

Use a GitHub Copilot subscription

To use the models of your Copilot subscription, give Copilot CLI a GitHub token instead of a provider key. Create a fine-grained personal access token with the Copilot Requests account permission (it starts with github_pat_). Classic tokens (ghp_) don’t work. Pass the token as COPILOT_GITHUB_TOKEN, and don’t set the COPILOT_PROVIDER_* variables, because they replace the Copilot models.
Environment variables are plain text, so any process in the sandbox, including the agent, can read the token. Give the token only the Copilot Requests permission, and delete it on GitHub’s token settings page if it leaks. Install Copilot CLI and run it as shown above. To pick one of your subscription’s models, pass --model. If the token is not valid, Copilot CLI exits with code 1 and prints Authentication token found but could not be validated. If no token and no provider are set, it prints No authentication information found.

Keep the version fixed

Copilot CLI checks for updates and downloads newer versions in the background, so a long-lived or resumed sandbox can end up on a newer version than the one you installed. Install a specific version and set COPILOT_AUTO_UPDATE to false to turn off updates:

Persist sessions

Delete when finished

A paused sandbox is kept until you delete it. When you no longer need the sandbox, delete it. This also deletes its files and saved state.
To delete it from another process, pass its ID to Sandbox.killById() (TypeScript) or Sandbox.kill_by_id() (Python). To delete paused sandboxes automatically, see Auto-delete.