{"meta":{"title":"백 엔드 서비스 설정","intro":"API, 웹 백 엔드, 마이크로 서비스 및 백그라운드 작업자와 같은 서버 쪽 애플리케이션에서 Copilot SDK를 실행합니다. CLI는 백 엔드 코드가 네트워크를 통해 연결하는 헤드리스 서버로 실행됩니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos","title":"방법"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"코필로트 SDK"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup","title":"Copilot SDK 설정"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/backend-services","title":"백 엔드 서비스"}],"documentType":"article"},"body":"# 백 엔드 서비스 설정\n\nAPI, 웹 백 엔드, 마이크로 서비스 및 백그라운드 작업자와 같은 서버 쪽 애플리케이션에서 Copilot SDK를 실행합니다. CLI는 백 엔드 코드가 네트워크를 통해 연결하는 헤드리스 서버로 실행됩니다.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n**최적 대상:** 웹앱 백 엔드, API 서비스, 내부 도구, CI/CD 통합, 모든 서버 쪽 워크로드.\n\n## 작동 방식\n\nSDK가 CLI 자식 프로세스를 생성하는 대신 **헤드리스 서버 모드**에서 독립적으로 CLI를 실행합니다. 백엔드는 `Connection` 옵션(`URIConnection`)을 사용하여 TCP를 통해 여기에 연결합니다.\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-backend-services-diagram-0.png)\n\n**주요 특징:**\n\n* CLI는 영구 서버 프로세스로 실행됩니다(요청당 생성되지 않음)\n* TCP를 통해 SDK 연결 - CLI 및 앱은 다른 컨테이너에서 실행할 수 있습니다.\n* 여러 SDK 클라이언트가 하나의 CLI 서버를 공유할 수 있습니다.\n* 모든 인증 메서드(GitHub 토큰, env vars, BYOK)에서 작동합니다.\n\n다중 사용자 서버 모드의 경우 SDK 클라이언트를 구성하고 `mode: \"empty\"`세션당 사용자 자격 증명을 전달하며 각 세션에 대한 도구를 명시적으로 허용합니다. 전체 패턴은 [다중 테넌트 및 서버 배포](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/multi-tenancy)을 참조하세요.\n\n## 아키텍처: 자동 관리 및 외부 CLI\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-backend-services-diagram-1.png)\n\n## 1단계: 헤드리스 모드에서 CLI를 시작합니다\n\nCLI를 백그라운드 서버로 실행합니다.\n\n```bash\n# Start with a specific port\ncopilot --headless --port 4321\n\n# Or let it pick a random port (prints the URL)\ncopilot --headless\n# Output: Listening on http://localhost:52431\n```\n\n기본적으로 헤드리스 서버는 루프백(`127.0.0.1`)의 연결만 허용합니다. 네트워크의 다른 컴퓨터와 같은 다른 호스트의 연결을 허용하려면 다음을 사용하여 루프백이 아닌 주소 `--host`에 바인딩합니다.\n\n```bash\ncopilot --headless --host 0.0.0.0 --port 4321\n```\n\n프로덕션의 경우 시스템 서비스 또는 컨테이너에서 실행합니다.\n\n> \\[!NOTE]\n> Copilot CLI에 대한 공식 미리 빌드된 Docker 이미지는 없습니다.\n> [GitHub 릴리스](https://github.com/github/copilot-cli/releases)에서 직접 빌드할 수 있습니다.\n\n```dockerfile\nFROM debian:bookworm-slim\nARG COPILOT_VERSION=1.0.7\nRUN apt-get update \\\n    && apt-get install -y --no-install-recommends ca-certificates wget \\\n    && ARCH=$(dpkg --print-architecture) \\\n    && case \"${ARCH}\" in amd64) COPILOT_ARCH=\"x64\" ;; arm64) COPILOT_ARCH=\"arm64\" ;; *) echo \"Unsupported: ${ARCH}\" && exit 1 ;; esac \\\n    && wget -q \"https://github.com/github/copilot-cli/releases/download/v${COPILOT_VERSION}/copilot-linux-${COPILOT_ARCH}.tar.gz\" \\\n    && tar -xzf \"copilot-linux-${COPILOT_ARCH}.tar.gz\" \\\n    && mv copilot /usr/local/bin/ \\\n    && rm \"copilot-linux-${COPILOT_ARCH}.tar.gz\" \\\n    && apt-get purge -y wget && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*\nENTRYPOINT [\"copilot\"]\n```\n\n```bash\n# Build the image\ndocker build --build-arg COPILOT_VERSION=1.0.7 -t copilot-cli:latest .\n\n# For remote deployments (Kubernetes, ACI, etc.), push to your registry\ndocker tag copilot-cli:latest your-registry/copilot-cli:latest\ndocker push your-registry/copilot-cli:latest\n```\n\n```bash\n# Docker — must bind to 0.0.0.0 so the container's published port is reachable\ndocker run -d --name copilot-cli \\\n    -p 4321:4321 \\\n    -e COPILOT_GITHUB_TOKEN=\"$TOKEN\" \\\n    copilot-cli:latest \\\n    --headless --host 0.0.0.0 --port 4321\n\n# systemd\n[Service]\nExecStart=/usr/local/bin/copilot --headless --port 4321\nEnvironment=COPILOT_GITHUB_TOKEN=your-token\nRestart=always\n```\n\n## 2단계: SDK 연결\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient, RuntimeConnection } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    connection: RuntimeConnection.forUri(\"localhost:4321\"),\n    mode: \"empty\",\n});\n\nconst session = await client.createSession({\n    sessionId: `user-${userId}-${Date.now()}`,\n    model: \"gpt-5.4\",\n    availableTools: [\"custom:*\"],\n    gitHubToken: user.githubToken,\n});\n\nconst response = await session.sendAndWait({ prompt: req.body.message });\nres.json({ content: response?.data.content });\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, RuntimeConnection\nfrom copilot.session import PermissionHandler\n\nclient = CopilotClient(\n    connection=RuntimeConnection.for_uri(\"localhost:4321\"),\n)\nawait client.start()\n\nsession = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5.4\", session_id=f\"user-{user_id}-{int(time.time())}\")\n\nresponse = await session.send_and_wait(message)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.URIConnection{URL: \"localhost:4321\"},\n})\nclient.Start(ctx)\ndefer client.Stop()\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n    SessionID: fmt.Sprintf(\"user-%s-%d\", userID, time.Now().Unix()),\n    Model:     \"gpt-5.4\",\n})\n\nresponse, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    Connection = RuntimeConnection.ForUri(\"localhost:4321\"),\n});\n\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    SessionId = $\"user-{userId}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}\",\n    Model = \"gpt-5.4\",\n});\n\nvar response = await session.SendAndWaitAsync(\n    new MessageOptions { Prompt = message });\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar userId = \"user1\";\nvar message = \"Hello!\";\n\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setCliUrl(\"localhost:4321\")\n);\n\ntry {\n    client.start().get();\n\n    var session = client.createSession(new SessionConfig()\n        .setSessionId(String.format(\"user-%s-%d\", userId, System.currentTimeMillis() / 1000))\n        .setModel(\"gpt-5.4\")\n        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    var response = session.sendAndWait(new MessageOptions()\n        .setPrompt(message)).get();\n} finally {\n    client.stop().get();\n}\n```\n\n</div>\n\n</div>\n\n## 백 엔드 서비스에 대한 인증\n\n### 환경 변수 토큰\n\n가장 간단한 방법은 CLI 서버에서 토큰을 설정하는 것입니다.\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-backend-services-diagram-2.png)\n\n```bash\n# All requests use this token\nexport COPILOT_GITHUB_TOKEN=\"gho_service_account_token\"\ncopilot --headless --port 4321\n```\n\n### 사용자별 토큰(OAuth)\n\n세션을 만들 때 개별 사용자 토큰을 전달합니다. 전체 흐름은 [GitHub OAuth 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/github-oauth)을 참조하세요.\n\n```typescript\nconst client = new CopilotClient({\n    connection: RuntimeConnection.forUri(\"localhost:4321\"),\n    mode: \"empty\",\n});\n\n// Your API receives user tokens from your auth layer\napp.post(\"/chat\", authMiddleware, async (req, res) => {\n    const session = await client.createSession({\n        sessionId: `user-${req.user.id}-chat`,\n        model: \"gpt-5.4\",\n        availableTools: [\"custom:*\"],\n        gitHubToken: req.user.githubToken,\n    });\n\n    const response = await session.sendAndWait({\n        prompt: req.body.message,\n    });\n\n    res.json({ content: response?.data.content });\n});\n```\n\n### BYOK(GitHub 인증 없음)\n\n모델 공급자에 대해 사용자 고유의 API 키를 사용합니다. 자세한 내용을 보려면 [BYOK(사용자 고유의 키 가져오기)](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/auth/byok)(을)를 참조하세요.\n\n```typescript\nconst client = new CopilotClient({\n    connection: RuntimeConnection.forUri(\"localhost:4321\"),\n});\n\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    provider: {\n        type: \"openai\",\n        baseUrl: \"https://api.openai.com/v1\",\n        apiKey: process.env.OPENAI_API_KEY,\n    },\n});\n```\n\n## 일반적인 백 엔드 패턴\n\n### Express를 사용하는 Web API\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-backend-services-diagram-3.png)\n\n```typescript\nimport express from \"express\";\nimport { CopilotClient, RuntimeConnection } from \"@github/copilot-sdk\";\n\nconst app = express();\napp.use(express.json());\n\n// Single shared CLI connection for multi-user server mode\nconst client = new CopilotClient({\n    connection: RuntimeConnection.forUri(process.env.CLI_URL || \"localhost:4321\"),\n    mode: \"empty\",\n});\n\napp.post(\"/api/chat\", async (req, res) => {\n    const { sessionId, message } = req.body;\n\n    // Create or resume session\n    let session;\n    try {\n        session = await client.resumeSession(sessionId);\n    } catch {\n        session = await client.createSession({\n            sessionId,\n            model: \"gpt-5.4\",\n            availableTools: [\"custom:*\"],\n            gitHubToken: req.user.githubToken,\n        });\n    }\n\n    const response = await session.sendAndWait({ prompt: message });\n    res.json({\n        sessionId,\n        content: response?.data.content,\n    });\n});\n\napp.listen(3000);\n```\n\n### 백그라운드 작업자\n\n```typescript\nimport { CopilotClient, RuntimeConnection } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    connection: RuntimeConnection.forUri(process.env.CLI_URL || \"localhost:4321\"),\n});\n\n// Process jobs from a queue\nasync function processJob(job: Job) {\n    const session = await client.createSession({\n        sessionId: `job-${job.id}`,\n        model: \"gpt-5.4\",\n    });\n\n    const response = await session.sendAndWait({\n        prompt: job.prompt,\n    });\n\n    await saveResult(job.id, response?.data.content);\n    await session.disconnect();  // Clean up after job completes\n}\n```\n\n### Docker Compose 배포\n\n```yaml\nversion: \"3.8\"\n\nservices:\n  copilot-cli:\n    image: copilot-cli:latest  # See \"Step 1\" above for how to build this image\n    command: [\"--headless\", \"--host\", \"0.0.0.0\", \"--port\", \"4321\"]\n    environment:\n      - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}\n    ports:\n      - \"4321:4321\"\n    restart: always\n    volumes:\n      - session-data:/root/.copilot/session-state\n\n  api:\n    build: .\n    environment:\n      - CLI_URL=copilot-cli:4321\n    depends_on:\n      - copilot-cli\n    ports:\n      - \"3000:3000\"\n\nvolumes:\n  session-data:\n```\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-backend-services-diagram-4.png)\n\n## 건강 상태 검사\n\nCLI 서버의 상태를 모니터링합니다.\n\n```typescript\n// Periodic health check\nasync function checkCLIHealth(): Promise<boolean> {\n    try {\n        const status = await client.getStatus();\n        return status !== undefined;\n    } catch {\n        return false;\n    }\n}\n```\n\n## 세션 정리\n\n백 엔드 서비스는 리소스 누출을 방지하기 위해 세션을 적극적으로 정리해야 합니다.\n\n```typescript\n// Clean up expired sessions periodically\nasync function cleanupSessions(maxAgeMs: number) {\n    const sessions = await client.listSessions();\n    const now = Date.now();\n\n    for (const session of sessions) {\n        const age = now - new Date(session.createdAt).getTime();\n        if (age > maxAgeMs) {\n            await client.deleteSession(session.sessionId);\n        }\n    }\n}\n\n// Run every hour\nsetInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000);\n```\n\n## Limitations\n\n| Limitation                  | Details                                                                                               |\n| --------------------------- | ----------------------------------------------------------------------------------------------------- |\n| **단일 CLI 서버 = 단일 실패 지점**    | HA 패턴은 [확장성 및 멀티 테넌시](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/scaling)을 참조하십시오. |\n| **SDK와 CLI 간에 기본 제공 인증 없음** | 네트워크 경로 보호(동일한 호스트, VPC 등)                                                                            |\n| **로컬 디스크의 세션 상태**           | 컨테이너 다시 시작을 위한 영구 스토리지 탑재                                                                             |\n| **30분 유휴 시간 제한**            | 활동이 없는 세션은 자동으로 정리됩니다.                                                                                |\n\n## 이동 시기\n\n| 필요                                                                                            | 다음 가이드 |\n| --------------------------------------------------------------------------------------------- | ------ |\n| 여러 CLI 서버/고가용성                                                                                |        |\n| [확장성 및 멀티 테넌시](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/scaling)         |        |\n| 동시 사용자에 대한 SDK 격리                                                                             |        |\n| [다중 테넌트 및 서버 배포](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/multi-tenancy) |        |\n| 사용자용 GitHub 계정 인증                                                                             |        |\n| [GitHub OAuth 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/github-oauth) |        |\n| 사용자 고유의 모델 키                                                                                  |        |\n| [BYOK(사용자 고유의 키 가져오기)](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/auth/byok)     |        |\n\n## 다음 단계\n\n* **[다중 테넌트 및 서버 배포](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/multi-tenancy)**: 동시 사용자에 대한 SDK 격리 구성\n* **[확장성 및 멀티 테넌시](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/scaling)**: 더 많은 사용자 처리, 중복성 추가\n* **[세션 다시 시작 및 지속성](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/session-persistence)**: 재시작 후에도 세션 복원\n* **[GitHub OAuth 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/github-oauth)**: 사용자 인증 추가"}