Default setup (bundled CLI)

Best for: Most applications—desktop apps, standalone tools, CLI utilities, prototypes, and more.

How it works

When you install the Copilot SDK, Copilot CLI is included automatically. The Copilot SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.

Key characteristics:

• Copilot CLI is included with the Copilot SDK—no separate install needed
• The Copilot SDK manages the CLI version to ensure compatibility
• Users authenticate through your app (or use env vars / BYOK)
• Sessions are managed per user on their machine

Quick start

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

For examples in Python, Go, .NET, and Java, see Default setup in the github/copilot-sdk repository. For Java, see the github/copilot-sdk-java repository.

Authentication strategies

You need to decide how your users will authenticate. Here are the common patterns:

Option A: user's signed-in credentials (simplest)

The user signs in to Copilot CLI once, and your app uses those credentials. No extra code needed—this is the default behavior.

const client = new CopilotClient();
// Default: uses signed-in user credentials

Option B: token via environment variable

Ship your app with instructions to set a token, or set it programmatically:

const client = new CopilotClient({
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),  // Your app provides the token
    },
});

Option C: BYOK (no GitHub auth needed)

If you manage your own model provider keys, users don't need GitHub accounts at all:

const client = new CopilotClient();

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

See Bring your own key (BYOK) for full details.

Session management

Apps typically want named sessions so users can resume conversations:

const client = new CopilotClient();

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-4.1",
});

// User closes app...
// Later, resume where they left off
const resumed = await client.resumeSession(sessionId);

Session state persists at ~/.copilot/session-state/{sessionId}/.

When to move on

Need	Next guide
Users signing in with GitHub accounts	Using GitHub OAuth with Copilot SDK
Run on a server instead of user machines	Setting up Copilot SDK for backend services
Use your own model keys	Bring your own key (BYOK)

Next steps

• Bring your own key (BYOK)
• Session persistence in the Copilot SDK
• Getting started with Copilot SDK