|
| 1 | +# Setup & Deployment Guide |
| 2 | + |
| 3 | +This guide explains how to configure the Copilot SDK for different deployment scenarios — from local development to production multi-user applications. |
| 4 | + |
| 5 | +## Quick Reference |
| 6 | + |
| 7 | +| Scenario | Configuration | Guide Section | |
| 8 | +|----------|--------------|---------------| |
| 9 | +| Local development | Default (no options) | [Local CLI](#local-cli) | |
| 10 | +| Multi-user app | `setGithubToken(userToken)` | [GitHub OAuth](#github-oauth-authentication) | |
| 11 | +| Server deployment | `setCliUrl("host:port")` | [Backend Services](#backend-services) | |
| 12 | +| Custom CLI location | `setCliPath("/path/to/copilot")` | [Bundled CLI](#bundled-cli) | |
| 13 | +| Own model keys | Provider configuration | [BYOK](advanced.html#Bring_Your_Own_Key_BYOK) | |
| 14 | + |
| 15 | +## Local CLI |
| 16 | + |
| 17 | +The simplest setup uses the Copilot CLI already signed in on your development machine. |
| 18 | + |
| 19 | +**Use when:** Building personal projects, prototyping, or learning the SDK. |
| 20 | + |
| 21 | +```java |
| 22 | +try (var client = new CopilotClient()) { |
| 23 | + client.start().get(); |
| 24 | + var session = client.createSession( |
| 25 | + new SessionConfig().setModel("gpt-4.1") |
| 26 | + ).get(); |
| 27 | + // Use session... |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +**How it works:** The SDK automatically spawns the CLI process and uses credentials from your system keychain. |
| 32 | + |
| 33 | +**Requirements:** |
| 34 | +- Copilot CLI installed and signed in (`copilot auth login`) |
| 35 | +- Active Copilot subscription |
| 36 | + |
| 37 | +See [Getting Started](getting-started.html) for a complete tutorial. |
| 38 | + |
| 39 | +## GitHub OAuth Authentication |
| 40 | + |
| 41 | +For multi-user applications where users authenticate with their GitHub accounts. |
| 42 | + |
| 43 | +**Use when:** Building apps where users have GitHub accounts and Copilot subscriptions. |
| 44 | + |
| 45 | +### Basic Setup |
| 46 | + |
| 47 | +After obtaining a user's GitHub OAuth token, pass it to the SDK: |
| 48 | + |
| 49 | +```java |
| 50 | +var options = new CopilotClientOptions() |
| 51 | + .setGithubToken(userAccessToken) |
| 52 | + .setUseLoggedInUser(false); |
| 53 | + |
| 54 | +try (var client = new CopilotClient(options)) { |
| 55 | + client.start().get(); |
| 56 | + var session = client.createSession( |
| 57 | + new SessionConfig().setModel("gpt-4.1") |
| 58 | + ).get(); |
| 59 | + // Requests are made on behalf of the authenticated user |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +### OAuth Flow Integration |
| 64 | + |
| 65 | +Your application handles the OAuth flow: |
| 66 | + |
| 67 | +1. Create a GitHub OAuth App in your GitHub settings |
| 68 | +2. Redirect users to GitHub's authorization URL |
| 69 | +3. Exchange the authorization code for an access token |
| 70 | +4. Pass the token to `CopilotClientOptions.setGithubToken()` |
| 71 | + |
| 72 | +### Per-User Client Management |
| 73 | + |
| 74 | +Each authenticated user should get their own client instance: |
| 75 | + |
| 76 | +```java |
| 77 | +private final Map<String, CopilotClient> clients = new ConcurrentHashMap<>(); |
| 78 | + |
| 79 | +public CopilotClient getClientForUser(String userId, String githubToken) { |
| 80 | + return clients.computeIfAbsent(userId, id -> { |
| 81 | + var options = new CopilotClientOptions() |
| 82 | + .setGithubToken(githubToken) |
| 83 | + .setUseLoggedInUser(false); |
| 84 | + var client = new CopilotClient(options); |
| 85 | + try { |
| 86 | + client.start().get(); |
| 87 | + } catch (Exception e) { |
| 88 | + throw new RuntimeException("Failed to start client for user: " + userId, e); |
| 89 | + } |
| 90 | + return client; |
| 91 | + }); |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +### Token Types |
| 96 | + |
| 97 | +| Token Prefix | Description | Supported | |
| 98 | +|--------------|-------------|-----------| |
| 99 | +| `gho_` | OAuth user access token | ✅ | |
| 100 | +| `ghu_` | GitHub App user access token | ✅ | |
| 101 | +| `github_pat_` | Fine-grained personal access token | ✅ | |
| 102 | + |
| 103 | +**Note:** Token lifecycle management (storage, refresh, expiration) is your application's responsibility. |
| 104 | + |
| 105 | +## Backend Services |
| 106 | + |
| 107 | +Run the SDK in server-side applications by connecting to an external CLI server. |
| 108 | + |
| 109 | +**Use when:** Building web backends, APIs, microservices, or any server-side workload. |
| 110 | + |
| 111 | +### Architecture |
| 112 | + |
| 113 | +Instead of spawning a CLI process, your application connects to a separately-running CLI server: |
| 114 | + |
| 115 | +``` |
| 116 | +┌─────────────────┐ ┌─────────────────┐ |
| 117 | +│ Your Backend │ │ CLI Server │ |
| 118 | +│ │ │ (headless) │ |
| 119 | +│ ┌───────────┐ │ │ ┌───────────┐ │ |
| 120 | +│ │ SDK ├──┼──────►│ │JSON-RPC │ │ |
| 121 | +│ └───────────┘ │ TCP │ │:4321 │ │ |
| 122 | +└─────────────────┘ │ └───────────┘ │ |
| 123 | + └─────────────────┘ |
| 124 | +``` |
| 125 | + |
| 126 | +### Start the CLI Server |
| 127 | + |
| 128 | +Run the CLI in headless server mode: |
| 129 | + |
| 130 | +```bash |
| 131 | +copilot server --port 4321 |
| 132 | +``` |
| 133 | + |
| 134 | +Or with authentication: |
| 135 | + |
| 136 | +```bash |
| 137 | +export GITHUB_TOKEN=your_token |
| 138 | +copilot server --port 4321 |
| 139 | +``` |
| 140 | + |
| 141 | +### Connect from Your Application |
| 142 | + |
| 143 | +Configure the SDK to connect to the external server: |
| 144 | + |
| 145 | +```java |
| 146 | +var options = new CopilotClientOptions() |
| 147 | + .setCliUrl("localhost:4321"); |
| 148 | + |
| 149 | +try (var client = new CopilotClient(options)) { |
| 150 | + client.start().get(); |
| 151 | + // Client connects to the external server |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +### Multiple SDK Clients, One Server |
| 156 | + |
| 157 | +Multiple application instances can share a single CLI server: |
| 158 | + |
| 159 | +```java |
| 160 | +// In different parts of your application or different containers |
| 161 | +var client1 = new CopilotClient(new CopilotClientOptions().setCliUrl("cli-server:4321")); |
| 162 | +var client2 = new CopilotClient(new CopilotClientOptions().setCliUrl("cli-server:4321")); |
| 163 | +// Both connect to the same CLI server |
| 164 | +``` |
| 165 | + |
| 166 | +### Deployment Patterns |
| 167 | + |
| 168 | +**Container deployment:** |
| 169 | +```yaml |
| 170 | +# docker-compose.yml |
| 171 | +services: |
| 172 | + cli-server: |
| 173 | + image: copilot-cli:latest |
| 174 | + command: copilot server --port 4321 |
| 175 | + environment: |
| 176 | + - GITHUB_TOKEN=${GITHUB_TOKEN} |
| 177 | + ports: |
| 178 | + - "4321:4321" |
| 179 | + |
| 180 | + backend: |
| 181 | + image: your-backend:latest |
| 182 | + environment: |
| 183 | + - CLI_URL=cli-server:4321 |
| 184 | + depends_on: |
| 185 | + - cli-server |
| 186 | +``` |
| 187 | +
|
| 188 | +**Kubernetes deployment:** |
| 189 | +```yaml |
| 190 | +apiVersion: v1 |
| 191 | +kind: Service |
| 192 | +metadata: |
| 193 | + name: copilot-cli |
| 194 | +spec: |
| 195 | + selector: |
| 196 | + app: copilot-cli |
| 197 | + ports: |
| 198 | + - port: 4321 |
| 199 | +--- |
| 200 | +apiVersion: apps/v1 |
| 201 | +kind: Deployment |
| 202 | +metadata: |
| 203 | + name: copilot-cli |
| 204 | +spec: |
| 205 | + replicas: 1 |
| 206 | + template: |
| 207 | + spec: |
| 208 | + containers: |
| 209 | + - name: cli |
| 210 | + image: copilot-cli:latest |
| 211 | + args: ["server", "--port", "4321"] |
| 212 | + env: |
| 213 | + - name: GITHUB_TOKEN |
| 214 | + valueFrom: |
| 215 | + secretKeyRef: |
| 216 | + name: copilot-auth |
| 217 | + key: token |
| 218 | +``` |
| 219 | +
|
| 220 | +## Bundled CLI |
| 221 | +
|
| 222 | +Package the Copilot CLI with your application so users don't need to install it separately. |
| 223 | +
|
| 224 | +**Use when:** Distributing desktop applications or standalone tools. |
| 225 | +
|
| 226 | +### Configuration |
| 227 | +
|
| 228 | +Point the SDK to your bundled CLI binary: |
| 229 | +
|
| 230 | +```java |
| 231 | +var options = new CopilotClientOptions() |
| 232 | + .setCliPath("./bundled/copilot"); // Relative to working directory |
| 233 | + |
| 234 | +try (var client = new CopilotClient(options)) { |
| 235 | + client.start().get(); |
| 236 | + // SDK uses the bundled CLI |
| 237 | +} |
| 238 | +``` |
| 239 | + |
| 240 | +### Packaging |
| 241 | + |
| 242 | +1. Download the appropriate CLI binary for your target platform |
| 243 | +2. Include it in your application bundle: |
| 244 | + ``` |
| 245 | + my-app/ |
| 246 | + ├── bin/ |
| 247 | + │ └── copilot # CLI binary |
| 248 | + ├── lib/ |
| 249 | + │ └── my-app.jar |
| 250 | + └── run.sh |
| 251 | + ``` |
| 252 | +3. Configure the path in your application |
| 253 | + |
| 254 | +### Platform-Specific Binaries |
| 255 | + |
| 256 | +For cross-platform applications, detect the platform and use the appropriate binary: |
| 257 | + |
| 258 | +```java |
| 259 | +private String getCliPathForPlatform() { |
| 260 | + String os = System.getProperty("os.name").toLowerCase(); |
| 261 | + String arch = System.getProperty("os.arch").toLowerCase(); |
| 262 | + |
| 263 | + if (os.contains("win")) { |
| 264 | + return "./bin/copilot-windows-" + arch + ".exe"; |
| 265 | + } else if (os.contains("mac")) { |
| 266 | + return "./bin/copilot-darwin-" + arch; |
| 267 | + } else { |
| 268 | + return "./bin/copilot-linux-" + arch; |
| 269 | + } |
| 270 | +} |
| 271 | + |
| 272 | +var options = new CopilotClientOptions() |
| 273 | + .setCliPath(getCliPathForPlatform()); |
| 274 | +``` |
| 275 | + |
| 276 | +## Scaling & Multi-Tenancy |
| 277 | + |
| 278 | +For applications serving many concurrent users, consider these patterns: |
| 279 | + |
| 280 | +### Session Isolation |
| 281 | + |
| 282 | +Each user's sessions are automatically isolated within their client instance. For strongest isolation, use one CLI server per user: |
| 283 | + |
| 284 | +```java |
| 285 | +// Pattern: Isolated CLI per user (requires CLI server per user) |
| 286 | +public CopilotClient createIsolatedClient(String userId, int port) { |
| 287 | + // Start CLI server for this user: copilot server --port {port} |
| 288 | + var options = new CopilotClientOptions() |
| 289 | + .setCliUrl("localhost:" + port); |
| 290 | + return new CopilotClient(options); |
| 291 | +} |
| 292 | +``` |
| 293 | + |
| 294 | +### Resource Management |
| 295 | + |
| 296 | +For high-concurrency scenarios: |
| 297 | + |
| 298 | +```java |
| 299 | +// Use a client pool with bounded resources |
| 300 | +public class CopilotClientPool { |
| 301 | + private final Semaphore permits; |
| 302 | + private final CopilotClient sharedClient; |
| 303 | + |
| 304 | + public CopilotClientPool(int maxConcurrentSessions) { |
| 305 | + this.permits = new Semaphore(maxConcurrentSessions); |
| 306 | + this.sharedClient = new CopilotClient(/* options */); |
| 307 | + } |
| 308 | + |
| 309 | + public <T> T withSession(SessionConfig config, |
| 310 | + Function<CopilotSession, T> action) throws Exception { |
| 311 | + permits.acquire(); |
| 312 | + try { |
| 313 | + var session = sharedClient.createSession(config).get(); |
| 314 | + try { |
| 315 | + return action.apply(session); |
| 316 | + } finally { |
| 317 | + session.close(); |
| 318 | + } |
| 319 | + } finally { |
| 320 | + permits.release(); |
| 321 | + } |
| 322 | + } |
| 323 | +} |
| 324 | +``` |
| 325 | + |
| 326 | +### Horizontal Scaling |
| 327 | + |
| 328 | +When scaling beyond a single server: |
| 329 | + |
| 330 | +1. Run multiple CLI servers (one per app server or shared) |
| 331 | +2. Use load balancing at the application tier |
| 332 | +3. Each app server connects to its assigned CLI server via `setCliUrl()` |
| 333 | + |
| 334 | +## Configuration Reference |
| 335 | + |
| 336 | +Complete list of `CopilotClientOptions` settings: |
| 337 | + |
| 338 | +| Option | Type | Description | Default | |
| 339 | +|--------|------|-------------|---------| |
| 340 | +| `cliPath` | String | Path to CLI executable | `"copilot"` from PATH | |
| 341 | +| `cliUrl` | String | External CLI server URL | `null` (spawn process) | |
| 342 | +| `cliArgs` | String[] | Extra CLI arguments | `null` | |
| 343 | +| `githubToken` | String | GitHub OAuth token | `null` | |
| 344 | +| `useLoggedInUser` | Boolean | Use system credentials | `true` | |
| 345 | +| `useStdio` | boolean | Use stdio transport | `true` | |
| 346 | +| `port` | int | TCP port for CLI | `0` (random) | |
| 347 | +| `autoStart` | boolean | Auto-start server | `true` | |
| 348 | +| `autoRestart` | boolean | Auto-restart on crash | `true` | |
| 349 | +| `logLevel` | String | CLI log level | `"info"` | |
| 350 | +| `environment` | Map | Environment variables | inherited | |
| 351 | +| `cwd` | String | Working directory | current dir | |
| 352 | + |
| 353 | +## Best Practices |
| 354 | + |
| 355 | +### Development |
| 356 | + |
| 357 | +- Use default configuration (local CLI) for fastest iteration |
| 358 | +- Enable debug logging: `setLogLevel("debug")` |
| 359 | +- Test with multiple models to ensure compatibility |
| 360 | + |
| 361 | +### Production |
| 362 | + |
| 363 | +- Use external CLI servers (`setCliUrl`) for better resource management |
| 364 | +- Implement health checks on the CLI server endpoint |
| 365 | +- Monitor CLI server resource usage (CPU, memory) |
| 366 | +- Use connection pooling for high-concurrency scenarios |
| 367 | +- Implement proper token refresh for OAuth-based auth |
| 368 | +- Set appropriate timeouts for session operations |
| 369 | + |
| 370 | +### Security |
| 371 | + |
| 372 | +- Never log or expose GitHub tokens |
| 373 | +- Use environment variables for tokens in production |
| 374 | +- Regularly rotate tokens |
| 375 | +- Implement proper access controls for multi-user apps |
| 376 | +- Validate user input before sending to sessions |
| 377 | + |
| 378 | +## Next Steps |
| 379 | + |
| 380 | +- **[Getting Started](getting-started.html)** - Complete tutorial |
| 381 | +- **[Documentation](documentation.html)** - Core concepts |
| 382 | +- **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP servers |
| 383 | +- **[API Javadoc](apidocs/index.html)** - Complete API reference |
0 commit comments