GitHub Copilot CLI

The GitHub Copilot CLI exposes an ACP server with copilot --acp. CopilotACPAdapter drives that server from Band, so a Band participant is backed by Copilot. Copilot speaks vanilla ACP with no copilot/* extension methods, so no custom client profile is needed. For how ACP works and what the generic client adapter does, see ACP Overview and ACP Client Adapter.

Prerequisites

Complete the Setup tutorial first, then add the requirements specific to Copilot.

Install the ACP extra:

$
uv add "band-sdk[acp]"

Install the Copilot CLI and make sure copilot is on your PATH. See Set up Copilot CLI.

Authenticate Copilot. The CLI resolves credentials in this order:

1. COPILOT_GITHUB_TOKEN
2. GH_TOKEN
3. GITHUB_TOKEN
4. A stored copilot login (OS keychain, or <COPILOT_HOME>/config.json, default ~/.copilot)
5. An authenticated gh CLI
6. BYOK, your own LLM provider keys, with no GitHub token needed

Add an agent entry named copilot_acp_agent to agent_config.yaml:

1
copilot_acp_agent:
2
  agent_id: "<your-agent-uuid>"
3
  api_key: "<your-api-key>"

Connect Copilot CLI Locally

In the local setup the adapter spawns copilot --acp as a subprocess over stdio and injects Band tools through a loopback HTTP/SSE MCP server that Copilot calls over ACP.

1
import asyncio
2
import logging
3
import os
4
5
from dotenv import load_dotenv
6
7
from band import Agent
8
from band.adapters import CopilotACPAdapter, CopilotACPAdapterConfig
9
10
logging.basicConfig(level=logging.INFO)
11
logger = logging.getLogger(__name__)
12
13
14
async def main() -> None:
15
    load_dotenv()
16
17
    ws_url = os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket")
18
    rest_url = os.getenv("BAND_REST_URL", "https://app.band.ai")
19
    cwd = os.getenv("ACP_AGENT_CWD", ".")
20
    github_token = os.getenv("GITHUB_TOKEN")
21
22
    # Optional TCP transport: connect to an already-running `copilot --acp --port`
23
    # instead of spawning a local subprocess.
24
    host = os.getenv("COPILOT_ACP_HOST")
25
    port = os.getenv("COPILOT_ACP_PORT")
26
27
    config = CopilotACPAdapterConfig(
28
        host=host,
29
        port=int(port) if port else None,
30
        cwd=cwd,
31
        github_token=github_token,
32
        rest_url=rest_url,
33
        inject_band_tools=True,
34
    )
35
    adapter = CopilotACPAdapter(config)
36
37
    agent = Agent.from_config(
38
        "copilot_acp_agent",
39
        adapter=adapter,
40
        ws_url=ws_url,
41
        rest_url=rest_url,
42
    )
43
44
    logger.info("Starting GitHub Copilot ACP client bridge...")
45
    await agent.run()
46
47
48
if __name__ == "__main__":
49
    asyncio.run(main())

Run it:

$
uv run python copilot_acp.py

Environment variables

Configuration reference

CopilotACPAdapterConfig is a frozen dataclass passed as the adapter’s first argument.

The adapter also accepts additional_tools and features as keyword arguments.

Run in Docker

Both Docker topologies put Copilot in a container and connect the host-side Band SDK over TCP. Because Copilot cannot reach the SDK host’s loopback, both set inject_band_tools=False and point Copilot at a band-mcp server through an explicit mcp_servers entry.

1
config = CopilotACPAdapterConfig(
2
    host=settings.copilot_acp_host,
3
    port=settings.copilot_acp_port,
4
    cwd=settings.copilot_acp_cwd,
5
    inject_band_tools=False,  # Copilot is remote; it can't reach our loopback MCP
6
    mcp_servers=[
7
        {
8
            "type": "sse",
9
            "name": "band",
10
            "url": settings.band_mcp_sse_url,
11
            "headers": [],
12
        }
13
    ],
14
    rest_url=settings.band_rest_url,
15
)

Shared points for both topologies:

• copilot --acp --port <N> binds 127.0.0.1 only and has no host-bind flag, so Docker port publishing cannot reach it. Both images front the stdio ACP server with socat TCP-LISTEN:8080,fork,reuseaddr EXEC:"copilot --acp --allow-all-tools" on a routable port.
• ,fork execs a fresh copilot --acp per TCP connection, so a reconnect lands on a process with no prior in-memory sessions. The SDK replays the Band room’s transcript into the fresh session’s first prompt, so conversation context survives the restart.
• band-mcp speaks the older MCP SSE transport at /sse, not streamable HTTP, which is why the mcp_servers entry is {"type": "sse", ...}.
• band-mcp holds one Band identity, BAND_AGENT_KEY, and MCP clients present no credentials. That key must be the same agent as the host client.py uses, copilot_acp_agent in agent_config.yaml, or room tools return 404.
• band-mcp rejects SSE requests with HTTP 421 unless the caller’s Host header is allow-listed through ALLOWED_HOSTS.
• band-mcp’s chat and message tools take a chat_id argument per call. This differs from the in-process inject_band_tools path, which injects a room_id per tool.
• The ACP port is published on 127.0.0.1 only. This copilot --acp is unauthenticated and runs --allow-all-tools, so expose it off-host only behind your own auth.

Sidecar (Compose)

Source: examples/acp/copilot_docker/compose/. Copilot and band-mcp are independent, separately scalable services on one compose network. This is the cloud-style topology.

 host: client.py (Band SDK)  --TCP-->  copilot:8080     (published to host)
 copilot (container)         --SSE-->  band-mcp:3000    (compose network only)

The copilot service publishes 127.0.0.1:8080:8080 and depends on band-mcp. The band-mcp service only uses expose: 3000, so it is reachable inside the compose network and never published to the host. Compose sets ALLOWED_HOSTS='["band-mcp:*"]' for it, and points its BAND_BASE_URL at BAND_REST_URL.

$
GITHUB_TOKEN=
$
BAND_AGENT_KEY=
$
BAND_REST_URL=https://app.band.ai
$
BAND_WS_URL=wss://app.band.ai/api/v1/socket/websocket
$
$
# Optional overrides for client.py:
$
# COPILOT_ACP_HOST=localhost
$
# COPILOT_ACP_PORT=8080
$
# COPILOT_ACP_CWD=/
$
# BAND_MCP_SSE_URL=http://band-mcp:3000/sse

$
cd examples/acp/copilot_docker/compose
$
cp .env.example .env
$
# Fill GITHUB_TOKEN and BAND_AGENT_KEY (= copilot_acp_agent api_key from agent_config.yaml)
$
docker compose up --build
$
$
# in another shell, from the repo root:
$
uv run python examples/acp/copilot_docker/compose/client.py

Colocated

Source: examples/acp/copilot_docker/colocated/. Copilot and band-mcp run in one image. Copilot reaches Band tools over the container’s own loopback, and only the ACP port is published. This is the self-contained single unit with the simplest networking, one image, and no cross-service DNS.

 host: client.py (Band SDK)  --TCP-->  container:8080  (published)
 container:
   socat 0.0.0.0:8080  --stdio-->  copilot --acp
   copilot             --SSE---->  127.0.0.1:3000 (band-mcp)

entrypoint.sh requires GITHUB_TOKEN and BAND_AGENT_KEY, sets ALLOWED_HOSTS='["localhost:*","127.0.0.1:*"]' and BAND_BASE_URL="${BAND_REST_URL:-https://app.band.ai}", starts band-mcp on 127.0.0.1:3000, then execs socat.

$
GITHUB_TOKEN=
$
BAND_AGENT_KEY=
$
BAND_REST_URL=https://app.band.ai
$
BAND_WS_URL=wss://app.band.ai/api/v1/socket/websocket
$
$
# Optional overrides for client.py:
$
# COPILOT_ACP_HOST=localhost
$
# COPILOT_ACP_PORT=8080
$
# COPILOT_ACP_CWD=/
$
# BAND_MCP_SSE_URL=http://127.0.0.1:3000/sse

$
cd examples/acp/copilot_docker/colocated
$
cp .env.example .env
$
# Fill GITHUB_TOKEN and BAND_AGENT_KEY (= copilot_acp_agent api_key from agent_config.yaml)
$
docker build -t copilot-band-acp .
$
docker run --rm --env-file .env -p 127.0.0.1:8080:8080 copilot-band-acp
$
$
# in another shell, from the repo root:
$
uv run python examples/acp/copilot_docker/colocated/client.py

Choosing between them

Run in a Docker Sandbox

examples/acp/copilot_sandbox/ runs the Copilot CLI inside a Docker microVM sandbox (sbx) and drives it over ordinary stdio, with no TCP, no socat, and no port publishing. It adds microVM isolation, a host-side secret proxy so the GitHub token never enters the sandbox, and an auditable default-deny egress firewall.

One-time setup:

$
brew install docker/tap/sbx        # or see docs.docker.com/ai/sandboxes
$
sbx login                          # sign in to Docker (interactive)
$
sbx policy init balanced           # default-deny + common dev/GitHub/model APIs
$
$
sbx create --name copilot-band copilot /path/to/workspace
$
$
gh auth token | sbx secret set -g github

The adapter drives the sandbox through its command:

1
config = CopilotACPAdapterConfig(
2
    command=("sbx", "exec", "-i", sandbox, "copilot", "--acp"),
3
    cwd=workspace,
4
    inject_band_tools=False,  # sandbox egress blocks host loopback
5
    mcp_servers=mcp_servers,
6
    rest_url=rest_url,
7
)

SBX_SANDBOX names the sandbox and SBX_WORKSPACE is the absolute workspace path, which with sbx’s direct mount is also the in-sandbox cwd. Set BAND_MCP_SSE_URL=http://127.0.0.1:3000/sse only when the sandbox was created with the included band-mcp-kit, which installs band-mcp and starts it on the sandbox’s loopback.

$
cd examples/acp/copilot_sandbox
$
cp .env.example .env               # set SBX_SANDBOX (+ SBX_WORKSPACE if not cwd)
$
uv run python client.py

Test Your Agent

@Copilot Agent Summarize the files in the working directory.

Next Steps