GitHub Copilot Agent

Built-in Agent provider

copilotAgent()

A thin AML profile over GitHub Copilot CLI's native ACP server. AML owns evaluation, capability grants, structured results, cancellation, and cleanup; Copilot owns the coding-agent session and model access.

Best for

GitHub Copilot accounts that need an ACP coding Agent inside provider-neutral AML workflows.

Know before using

The provider uses an invocation-private Copilot home and never copies your interactive CLI configuration. Authentication follows the launched process environment, while trusted Workspaces can still contribute native MCP configuration.

Built-in Native ACP Credentialed

What this provider launches

copilotAgent() launches copilot --acp by default:

<Agent>
  AML normalizes model, system, permissions, Tools, MCP, and output
        ↓
  copilot --acp
        ↓
  GitHub Copilot model session

Each Agent acquisition receives an invocation-private COPILOT_HOME. This prevents the workflow from loading the operator’s saved OAuth login, MCP servers, permissions, settings, sessions, plugins, or instructions. The provider also starts Copilot with custom instructions, built-in MCP, remote control, and automatic updates disabled. Copilot’s automatic login discovery is also disabled so it does not fall back to stored credentials outside COPILOT_HOME.

Interactive login is intentionally not inherited

Running copilot login writes authentication into the interactive Copilot home. AML does not read or copy that file. Provide a fine-grained token through the runtime environment, or prepare an application-owned command/runtime explicitly. Never make a deployment depend on a developer’s private Copilot directory.

Prerequisites

Install Copilot CLI

Install GitHub Copilot CLI in every trusted host or Sandbox image where AML can launch the Agent. AML does not install runtime software during evaluation.

Provide explicit authentication

Make one of Copilot CLI’s supported authentication variables available in the launched runtime. Fine-grained tokens require the Copilot Requests permission.

Confirm account policy

The GitHub account must have Copilot CLI access, and organization policy must permit the CLI and selected model.

Install and verify

Install Copilot CLI in the environment where the Agent process will run, then inspect that exact executable:

Terminal

npm install --global @github/copilot
copilot --version
copilot help environment

The AML repository pins @github/copilot@1.0.80 for deterministic development and smoke setup. That is the verified baseline for this provider, not a guarantee that every newer release preserves the same ACP behavior. Use the pinned version when reproducing repository tests:

Terminal

npm install --global @github/copilot@1.0.80

The Copilot image variant includes this pinned baseline. The default full image includes it too. Local Sandbox still requires Copilot CLI on the host.

Install it where Copilot runs

A host-global installation is visible to localSandbox(). Docker, Daytona, Modal, or another remote Sandbox needs Copilot CLI in its own image or environment. Run copilot --version through the same execution path before debugging AML configuration.

Complete example

This example uses the highest-priority Copilot token variable explicitly, selects gpt-5-mini, and runs against an existing local repository. Local Sandbox needs read-write access to start the Copilot process and is suitable only for trusted development; use a hardened Sandbox when read-only access or hostile-input isolation is required.

import { Agent, AmlRuntime, Sandbox, Workspace, copilotAgent, localSandbox, localWorkspace } from "@aml-jsx/sdk"

const token = process.env.COPILOT_GITHUB_TOKEN
if (!token) throw new Error("COPILOT_GITHUB_TOKEN is required")

const provider = copilotAgent({
  env: { COPILOT_GITHUB_TOKEN: token },
  model: "gpt-5-mini",
  reasoningEffort: "low",
})

const result = await new AmlRuntime({
  agentProvider: provider,
}).evaluate(
  <Workspace
    id="copilot-review"
    provider={localWorkspace({ directory: "/absolute/path/to/repository" })}
    load={false}
    save={false}
  >
    <Sandbox provider={localSandbox()} access="read-write">
      <Agent system="Return concise, evidence-based answers.">
        Summarize this repository and identify its primary runtime boundary.
      </Agent>
    </Sandbox>
  </Workspace>
)

console.log(result)

The example maps one application-owned token into the native variable Copilot already understands. No token mapping is required when the launched environment is already configured correctly. Do not put credentials in a Workspace, prompt, or repository file.

Options and precedence

Option	Type	Default	Semantics
command	string	"copilot"	Copilot ACP executable or application-owned launcher.
args	readonly string[]	[]	Extra Copilot arguments inserted before AML-owned ACP, isolation, model, and policy flags.
env	Record<string, string>	{}	Optional runtime environment overlay; AML does not filter or rewrite credential variables.
model	string	"auto"	Provider-level model fallback.
reasoningEffort	string	—	Provider-native value passed through as Copilot’s reasoning-effort flag.
workingDirectory	string	—	Fallback cwd when no active Sandbox supplies one.

Values such as "low" in the examples are provider-native examples, not an AML allowlist. AML only checks that the value is a normalized non-empty string without null bytes, then forwards it to Copilot unchanged.

Precedence is deliberate:

1. <Agent model="..." /> overrides the factory model.
2. The factory defaults to auto, which lets Copilot select from the models available to the authenticated account.
3. Authored AML system content becomes an explicit first-turn prelude inside literal <SYSTEM> tags because ACP has no portable system-message field.
4. AML-owned launch flags are appended after args, so factory arguments cannot replace ACP mode, private state, capability isolation, or portable permission policy.
5. An active Sandbox supplies the effective cwd; otherwise workingDirectory or the application cwd is used.

Authentication and private state

The provider always sets:

COPILOT_HOME=<invocation-private AML state directory>

It never copies ~/.copilot/config.json and never points COPILOT_HOME at the operator’s interactive configuration. Within each environment source, authentication variables use this order:

COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN

Explicit token configuration in copilotAgent({ env }) wins as a source, regardless of ambient variables. A local launch then checks the inherited process.env when no token was configured explicitly. AML passes the selected variable name to Copilot CLI without copying or renaming its value.

A remote Sandbox does not inherit the AML host’s process.env. When no token is present in the provider env, AML leaves selection to Copilot CLI inside the Sandbox, preserving credentials supplied by that runtime’s native secret mechanism. This prevents a host variable from changing which Sandbox credential is used.

AML does not bulk-copy the host’s process.env into a provisioned remote Sandbox. Pass deliberate values through the provider env option or configure secrets in that Sandbox/deployment. The Sandbox provider may also supply its own environment according to its native contract.

Permissions and capabilities

AML request	Copilot launch mapping	Boundary that still matters
filesystem: "read-write"	Standard Copilot tools; ACP approvals handled non-interactively.	Host or Sandbox controls actual filesystem authority.
filesystem: "read-only"	Denies Copilot’s write permission kind and hides edit/write tools.	Sandbox remains the hard filesystem boundary.
shell: false	Denies Copilot’s shell permission kind and hides bash.	Sandbox process policy remains authoritative.
network: false	Denies URLs and hides Copilot web fetch/search tools.	Sandbox or deployment egress policy must contain shell/network.

Copilot’s deny rules take precedence over ACP approvals. They narrow the model-visible tool set and avoid wasted tool attempts, but they do not turn the trusted local launcher into an isolation boundary.

State isolation and lifecycle

For every acquired Copilot session, AML creates a fresh temporary directory and launches Copilot with:

COPILOT_HOME             <invocation state directory>
--log-dir                logs remain in the invocation state directory
--no-custom-instructions no AGENTS.md or related instruction loading
--disable-builtin-mcps   no built-in GitHub MCP server
--auth-token-env         use the selected provider or local token variable when AML can inspect it
--no-auto-login          no interactive or stored-credential fallback
--no-remote              no remote control
--no-remote-export       no session export to GitHub web or mobile

--disable-builtin-mcps removes Copilot’s own default MCP servers and the private COPILOT_HOME prevents user-level MCP configuration from leaking into the evaluation. AML-authored Tools and MCP servers still use the shared Agent capability path described in the related documentation below.

Workspace MCP discovery remains Copilot-native

Copilot CLI can load .mcp.json and .github/mcp.json from a trusted working directory even in ACP server mode. --disable-builtin-mcps does not disable those files, and AML’s allowedMcpServers policy governs AML-authored MCP declarations rather than Copilot’s native workspace discovery. Review or remove native workspace MCP configuration when the evaluation requires a closed capability inventory.

AML starts the ACP process only after the effective Sandbox cwd, permissions, Tools, MCP servers, model, and system text are known. On release it closes the session, terminates the process, and removes the invocation state directory. Reusing one copilotAgent() factory does not reuse Copilot state between evaluations.

Failure modes and troubleshooting

1. Authentication required

   Supply a supported token through the runtime environment. An interactive copilot login is not imported into the private AML invocation. Explicit provider token configuration wins over inherited local variables. Within either source, precedence is COPILOT_GITHUB_TOKEN, then GH_TOKEN, then GITHUB_TOKEN. An unconfigured remote Sandbox uses Copilot’s native discovery inside that runtime.

2. Model unavailable

   Use model: "auto" or a model enabled for the account and organization. gpt-5-mini is a useful low-cost smoke model when available.

3. Command not found

   Install copilot in the exact host or Sandbox image used by the Agent, or set command to an application-owned launcher.

4. Repository instructions are ignored

   This is intentional: AML passes --no-custom-instructions, so Copilot does not load AGENTS.md, CLAUDE.md, or GitHub Copilot instruction files. Put evaluation instructions in <Agent system> or authored AML content.

5. The Agent can do more than expected

   Inspect Copilot launch flags, native .mcp.json or .github/mcp.json files, and the enclosing Sandbox. ACP permission mapping is policy; the Sandbox is the security boundary.

Provider references

Copilot CLI ACP serverGitHub's native ACP server behavior and integration contract.

Copilot CLI command referenceLaunch flags, models, environment, permissions, and runtime behavior.

Authenticating Copilot CLIToken variables, credential precedence, OAuth storage, and organization policy.

Allowing and denying toolsCopilot tool availability and permission-rule semantics.

Copilot network allowlistGitHub hostnames that restricted execution environments must permit.

AML Copilot profile sourceProfile implementation, deterministic tests, and credentialed integration test.

Related AML documentation

Use the shared AML documentation for capabilities that behave the same across ACP Agent providers:

JavaScript ToolsDefine, scope, validate, and operate an application-owned Tool.

Model Context ProtocolDeclare MCP servers, transports, allowlists, and runtime requirements.

Runtime configurationConfigure limits, cancellation, lifecycle events, tracing, and cleanup.

Agent component referenceReview Agent props, resolution, capability scope, and result behavior.