# Setup guides

These guides walk you through configuring the Copilot SDK for your specific use case—from personal side projects to production platforms serving thousands of users.

## Architecture at a glance

Every Copilot SDK integration follows the same core pattern: your application talks to the SDK, which communicates with the Copilot CLI over JSON-RPC. What changes across setups is **where the CLI runs**, **how users authenticate**, and **how sessions are managed**.

```mermaid
flowchart TB
    subgraph YourApp["Your Application"]
        SDK["SDK Client"]
    end

    subgraph CLI["Copilot CLI"]
        direction TB
        RPC["JSON-RPC Server"]
        Auth["Authentication"]
        Sessions["Session Manager"]
        Models["Model Provider"]
    end

    SDK -- "JSON-RPC<br/>(stdio or TCP)" --> RPC
    RPC --> Auth
    RPC --> Sessions
    Auth --> Models

    style YourApp fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
    style CLI fill:#161b22,stroke:#3fb950,color:#c9d1d9
```

The setup guides below help you configure each layer for your scenario.

## Who are you?

### 🧑‍💻 Hobbyist

You're building a personal assistant, side project, or experimental app. You want the simplest path to getting Copilot in your code.

**Start with:**
1. **[Default Setup](./bundled-cli.md)**—The SDK includes the CLI automatically—just install and go
1. **[Local CLI](./local-cli.md)**—Use your own CLI binary or running instance (advanced)

### 🏢 Internal app developer

You're building tools for your team or company. Users are employees who need to authenticate with their enterprise GitHub accounts or org memberships.

**Start with:**
1. **[GitHub OAuth](./github-oauth.md)**—Let employees sign in with their GitHub accounts
1. **[Backend Services](./backend-services.md)**—Run the SDK in your internal services

**If scaling beyond a single server:**
1. **[Multi-tenancy and server deployments](./multi-tenancy.md)**—Configure SDK options for multi-user server mode
1. **[Scaling & Multi-Tenancy](./scaling.md)**—Handle multiple users and services

### 🚀 App developer (ISV)

You're building a product for customers. You need to handle authentication for your users—either through GitHub or by managing identity yourself.

**Start with:**
1. **[GitHub OAuth](./github-oauth.md)**—Let customers sign in with GitHub
1. **[BYOK](../auth/byok.md)**—Manage identity yourself with your own model keys
1. **[Backend Services](./backend-services.md)**—Power your product from server-side code

**For production:**
1. **[Multi-tenancy and server deployments](./multi-tenancy.md)**—Use `mode: "empty"`, per-session tokens, and isolated runtime state
1. **[Scaling & Multi-Tenancy](./scaling.md)**—Serve many customers reliably

### 🏗️ Platform developer

You're embedding Copilot into a platform—APIs, developer tools, or infrastructure that other developers build on. You need fine-grained control over sessions, scaling, and multi-tenancy.

**Start with:**
1. **[Backend Services](./backend-services.md)**—Core server-side integration
1. **[Multi-tenancy and server deployments](./multi-tenancy.md)**—SDK-level isolation, per-session auth, and shared runtime options
1. **[Scaling & Multi-Tenancy](./scaling.md)**—Session isolation, horizontal scaling, persistence

**Depending on your auth model:**
1. **[GitHub OAuth](./github-oauth.md)**—For GitHub-authenticated users
1. **[BYOK](../auth/byok.md)**—For self-managed identity and model access

## Decision matrix

Use this table to find the right guides based on what you need to do:

| What you need | Guide |
|---------------|-------|
| Getting started quickly | [Default Setup (Bundled CLI)](./bundled-cli.md) |
| Use your own CLI binary or server | [Local CLI](./local-cli.md) |
| Users sign in with GitHub | [GitHub OAuth](./github-oauth.md) |
| Use your own model keys (OpenAI, Azure, etc.) | [BYOK](../auth/byok.md) |
| Azure BYOK with Managed Identity (no API keys) | [Azure Managed Identity](./azure-managed-identity.md) |
| Run the SDK on a server | [Backend Services](./backend-services.md) |
| Configure SDK options for concurrent users | [Multi-tenancy and server deployments](./multi-tenancy.md) |
| Serve multiple users / scale horizontally | [Scaling & Multi-Tenancy](./scaling.md) |

## Configuration comparison

```mermaid
flowchart LR
    subgraph Auth["Authentication"]
        A1["Signed-in CLI<br/>(local)"]
        A2["GitHub OAuth<br/>(multi-user)"]
        A3["Env Vars / Tokens<br/>(server)"]
        A4["BYOK<br/>(your keys)"]
    end

    subgraph Deploy["Deployment"]
        D1["Local Process<br/>(auto-managed)"]
        D2["Bundled Binary<br/>(shipped with app)"]
        D3["External Server<br/>(headless CLI)"]
    end

    subgraph Scale["Scaling"]
        S1["Single User<br/>(one CLI)"]
        S2["Multi-User<br/>(shared CLI)"]
        S3["Isolated<br/>(CLI per user)"]
    end

    A1 --> D1 --> S1
    A2 --> D3 --> S2
    A3 --> D3 --> S2
    A4 --> D2 --> S1
    A2 --> D3 --> S3
    A3 --> D3 --> S3

    style Auth fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
    style Deploy fill:#0d1117,stroke:#3fb950,color:#c9d1d9
    style Scale fill:#0d1117,stroke:#f0883e,color:#c9d1d9
```

## Prerequisites

All guides assume you have:

* **One of the SDKs** installed (Node.js, Python, and .NET SDKs include the CLI automatically):
  * Node.js: `npm install @github/copilot-sdk`
  * Python: `pip install github-copilot-sdk`
  * Go: `go get github.com/github/copilot-sdk/go` (requires separate CLI installation)
  * .NET: `dotnet add package GitHub.Copilot.SDK`

If you're brand new, start with the **[Getting Started tutorial](../getting-started.md)** first, then come back here for production configuration.

## Next steps

Pick the guide that matches your situation from the [decision matrix](#decision-matrix) above, or start with the persona description closest to your role.