Chorus 데몬 운영

포그라운드 데몬 연결을 확인한 뒤에 이 가이드를 사용하세요. 명령은 지원되는 상주 백엔드, 즉 Claude Code, Codex, Kiro, Pi에 적용됩니다.

데몬이 접근할 수 있는 범위 정하기

각 --cwd는 하나의 작업 디렉터리를 Chorus에서 별개의 대상으로 등록합니다.

chorus daemon \
  --agent claude-code \
  --cwd ~/work/project-a \
  --cwd ~/work/project-b \
  --chorus-only

--cwd가 없으면 Chorus는 명령을 시작한 디렉터리를 사용합니다. 반복 가능한 --browse-root 옵션은, 사용자가 더 넓은 루트 아래에서 디렉터리를 골라야 할 때만 사용하세요. browse root는 탐색을 허용할 뿐, 모든 디렉터리를 온라인 연결로 등록하지는 않습니다.

프로젝트의 에이전트에 대해 작업 디렉터리를 고정할 때, 그 경로는 이 데몬이 제공하는 것이어야 합니다. 이 데몬의 cwds 집합에 포함시켜, 고정된 디렉터리가 온라인 연결로 해석되게 하세요.

`daemon.json` 구성하기

데몬은 설정을 ~/.chorus/daemon.json에서 읽습니다. 흔한 단일 에이전트의 경우, 이것은 에이전트 인증 정보와 런타임 옵션을 함께 담는 단일의 평면 JSON 객체입니다. 하나의 데몬으로 여러 에이전트를 서비스하려면, 대신 그것들을 agents 배열에 나열합니다(아래 「하나의 데몬에서 여러 에이전트 실행하기」 절 참조). 어느 형식이든, 0600(소유자만 읽기/쓰기)으로, 임시 파일을 쓴 뒤 이름을 바꾸는 원자적 방식으로 기록되므로, 쓰기 도중 크래시가 나도 잘린 파일이 남지 않습니다. 경로는 ~/.chorus/daemon.json(홈 디렉터리에서 해석됨)로 고정되어 있으며, 파일 자체를 옮기는 환경 변수는 없습니다.

필드

필드	타입	의미
`url`	string	Chorus 서버 URL.
`apiKey`	string	에이전트 API 키(`cho_…`).
`agentUuid`	string	인증된 에이전트 UUID(참고용).
`agentName`	string	인증된 에이전트 이름(참고용).
`cwds`	string[]	이 데몬이 제공하는 작업 디렉터리. 각 경로는 하나의 독립된 온라인 연결입니다.
`browseRoots`	string[]	원격 작업 디렉터리 탐색에 노출하는 루트. browse root는 연결을 만들지 않습니다.
`agent`	string	깨울 로컬 백엔드: `"claude-code"`, `"codex"`, `"kiro"`, `"pi"`.
`sigintTimeoutMs`	number	`SIGINT` 이후 깨어난 에이전트를 강제 종료하기 전까지의 유예 시간(밀리초). 기본값 `10000`.
`agents`	object[]	선택. 하나의 데몬으로 여러 독립 에이전트를 서비스합니다. 각 항목은 해당 에이전트에 대해 상위 필드를 재정의합니다. 아래 「하나의 데몬에서 여러 에이전트 실행하기」 참조.

chorus login과 chorus daemon install 이후의 최소 파일.

{
  "url": "https://chorus.example.com",
  "apiKey": "cho_REDACTED",
  "agentUuid": "8a1c…",
  "agentName": "Build Agent",
  "cwds": ["/home/demo/work/project-a"],
  "browseRoots": ["/home/demo/work"],
  "agent": "claude-code",
  "sigintTimeoutMs": 10000
}

파일은 어떻게 만들어지는가

chorus agents add가 이 파일을 처음 만드는 통상적인 방법입니다. 구성된 각 에이전트의 인증 정보를 검증하고 agents 배열의 항목으로 씁니다. 에이전트 런타임 연결을 참고하세요.
chorus login은 URL과 키를 검증한 뒤, 단일 평면 에이전트에 대해 url, apiKey, agentUuid, agentName을 씁니다.
chorus daemon install은 추가로 cwds, browseRoots, agent를 씁니다(이들이 아직 설정되지 않았으면 제공할 디렉터리와 백엔드를 묻습니다).
터미널에서 chorus daemon을 처음 실행하면, 빠진 인증 정보를 대화식으로 채워 씁니다.

파일은 어떻게 갱신되는가

모든 기록 주체는 얕은 병합을 수행합니다. 새 필드는 디스크에 이미 있는 내용 위로 병합되고, 무관한 필드는 보존됩니다. chorus login을 다시 실행하면 cwds, agent, sigintTimeoutMs를 지우지 않고 인증 정보만 새로 고칩니다. chorus daemon install을 다시 실행하면 인증 정보를 버리지 않고 제공하는 집합을 갱신합니다. 파일이 없거나 손상되면 빈 객체로 취급되므로, 다시 로그인하면 실패하지 않고 항상 유효한 파일을 만들어 냅니다.

필드, 플래그, 환경 변수

각 옵션은 세 가지 방법으로 줄 수 있습니다. 우선순위는 플래그, 그다음 환경 변수, 마지막이 daemon.json이므로, 일회성 플래그나 환경 변수 재정의를 파일에 쓸 필요가 없습니다.

대상	`daemon.json` 필드	CLI 플래그	환경 변수
서버 URL	`url`	`--url`	`CHORUS_URL`
API 키	`apiKey`	`--api-key`	`CHORUS_API_KEY`
작업 디렉터리	`cwds`	`--cwd`(반복 가능)	`CHORUS_DAEMON_CWDS`
browse root	`browseRoots`	`--browse-root`(반복 가능)	`CHORUS_DAEMON_BROWSE_ROOTS`
백엔드	`agent`	`--agent`	`CHORUS_AGENT`
SIGINT 유예	`sigintTimeoutMs`	`--sigint-timeout`	`CHORUS_DAEMON_SIGINT_TIMEOUT`
권한 모드	(저장되지 않음)	`--yolo` / `--chorus-only`	`CHORUS_YOLO` / `CHORUS_CHORUS_ONLY`

권한 모드는 의도적으로 daemon.json에 저장되지 않습니다. 시작할 때 --chorus-only를 전달하거나(또는 CHORUS_CHORUS_ONLY=1 설정) 하세요. 설치된 서비스는 --chorus-only를 파일이 아니라 그 유닛에 담습니다.

하나의 데몬에서 여러 에이전트 실행하기

하나의 chorus daemon 프로세스는 여러 개의 완전히 독립된 에이전트를 동시에 실행할 수 있습니다. 페르소나, 권한, 계정, 심지어 백엔드가 서로 달라도 됩니다. 에이전트마다 별도의 데몬을 돌릴 필요가 없습니다. 그것들을 agents 배열에 나열하며, 각 항목이 하나의 에이전트입니다.

{
  "url": "https://chorus.example.com",
  "sigintTimeoutMs": 8000,
  "agents": [
    { "apiKey": "cho_alpha", "agentType": "claude-code", "cwds": ["/home/demo/project-a"] },
    { "apiKey": "cho_beta", "agentType": "kiro", "cwds": ["/home/demo/project-b"], "permissionMode": "chorus" }
  ]
}

상위 필드는 모두 기본값이 되고, 어떤 에이전트에 설정한 필드는 그 에이전트에 대해서만 기본값을 재정의합니다. 각 에이전트는 자신의 (키로 결정되는) 아이덴티티, 자신의 연결(cwds마다 하나), 자신의 깨우기 큐, 자신의 백엔드를 가집니다. 따라서 각자 독립적으로 깨어나 실행되며, 한 에이전트의 실패가 다른 에이전트를 방해하지 않습니다. 서버에서는 각 에이전트가 agent·호스트·디렉터리를 키로 하여 설정 → 에이전트(Settings → Agents)에 독립된 연결로 표시됩니다. 에이전트는 같은 작업 디렉터리를 공유할 수도 있지만, 데몬은 그것들을 직렬화하지 않으므로, 하나의 git 트리 안에서 충돌하는 작업을 동시에 하지 마세요(별도의 브랜치나 worktree를 사용하세요).

에이전트별 필드

필드	의미
`apiKey`(필수)	에이전트의 `cho_` 키 — 그 아이덴티티를 결정합니다.
`url`	Chorus 서버(에이전트마다 다를 수 있음 — 다른 서버나 회사).
`agentType`	`claude-code`, `codex`, `kiro`, `pi`(백엔드는 혼합 가능).
`cwds`	이 에이전트가 제공하는 작업 디렉터리(각각 하나의 연결).
`permissionMode`	`yolo` 또는 `chorus`.
`maxConcurrency`	이 에이전트 자신의 깨우기 동시 실행 상한(기본값 `4`).
`sigintTimeoutMs`	중단 에스컬레이션 유예 시간(밀리초).
`browseRoots`	디렉터리 탐색 허용 목록.

다른 에이전트 추가하기

chorus login --add 명령은 새 키를 검증하고 다른 에이전트로 추가합니다. 평면 파일에서 처음 --add를 사용하면, 기존 인증 정보를 agents[0]로 옮기고 새 키를 agents[1]로 추가합니다. 중복된 키는 거부되며, 기존 에이전트는 절대 덮어쓰지 않습니다.
chorus daemon install --add 명령은 설치 마법사를 반복 실행하여 한 번에 여러 에이전트를 추가할 수 있습니다(터미널만).
직접 편집 ~/.chorus/daemon.json은 항상 지원됩니다.

파일을 편집한 뒤에는 데몬을 재시작하고(chorus daemon restart), 설정 → 에이전트(Settings → Agents)에서 각 에이전트가 나타나는지 확인하세요.

각 백엔드는 자신의 키를 어떻게 받는가

각 에이전트는 자신의 키로 인증하지만, 그 키가 깨어난 하위 프로세스에 어떻게 도달하는지는 백엔드에 따라 다릅니다.

Claude Code — 자동. 데몬은 깨울 때마다 해당 에이전트의 URL과 키를 담은 MCP 설정을 씁니다. 구성할 것이 없습니다.
Kiro — 환경 변수를 통해 자동. 설치된 mcp.json은 ${CHORUS_URL}과 ${env:CHORUS_API_KEY}를 참조하고, 데몬이 깨울 때마다 이를 내보내므로, 각 Kiro 에이전트는 자신의 키로 인증합니다.
Codex — 환경 변수를 통해 자동. chorus agents add는 Codex를 keyless로 구성합니다. CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE를 ~/.codex/.env(Codex가 시작할 때 로드함)에 쓰고 config.toml에 bearer_token_env_var = "CHORUS_API_KEY"를 설정하므로, Codex는 리터럴 키가 아니라 환경 변수에서 자신의 키를 읽습니다. 데몬이 깨울 때마다 각 에이전트 자신의 키를 주입하므로, 하나의 데몬에 있는 여러 Codex 에이전트가 각자 자기 자신으로 인증합니다.
Pi — 환경 변수를 통해 자동. 데몬은 깨울 때마다 각 에이전트 자신의 CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE를 깨워진 pi 세션으로 내보내고, chorus-pi 확장이 이를 읽으므로, 각 pi 에이전트는 자신의 키로 인증합니다.

Linux 서비스 설치하기

Linux에서는 확인된 구성을 사용자 서비스로 설치합니다.

chorus daemon install \
  --agent claude-code \
  --cwd ~/work/project-a \
  --chorus-only

설치 프로그램은 서비스를 즉시 시작하고, 사용자가 로그인할 때 시작되도록 구성합니다. 서비스가 저장된 인증 정보를 읽을 수 있도록 먼저 chorus agents add(또는 chorus login)를 실행하세요. 또는 chorus agents add에 --daemon-autostart를 전달하면 같은 단계에서 이 부팅 서비스를 설치할 수 있습니다.

깨워진 에이전트가 필요로 하는 자격 증명 제공

데몬은 깨워진 에이전트에 Chorus 연결(CHORUS_URL, CHORUS_API_KEY, CHORUS_AGENT_PROFILE)만 주입하며, 모델 제공자 키는 절대 주입하지 않습니다. 어떤 백엔드가 모델 제공자 자격 증명을 환경에서 읽는다면, 그 자격 증명은 데몬 자신의 환경에 존재해야 합니다. systemd --user 서비스는 깨끗한 환경에서 시작하며 당신이 로그인 셸에서 내보낸 변수를 상속하지 않으므로, 드롭인으로 서비스에 설정한 뒤 재시작하세요.

[Service]
Environment=EXAMPLE_PROVIDER_API_KEY=…

systemctl --user daemon-reload && systemctl --user restart chorus-daemon

제공자 인증을 파일에서 읽는 백엔드(예: ~/.claude / ~/.codex 아래의 Claude Code와 Codex)는 데몬의 HOME만 올바르게 설정되면 되며, 설치된 유닛이 이미 이를 처리합니다.

일상적인 운영에는 다음 명령을 사용합니다.

chorus daemon status
chorus daemon logs
chorus daemon restart
chorus daemon stop
chorus daemon uninstall

인증 정보, 작업 디렉터리, 백엔드, 권한 모드를 바꾼 뒤에는 서비스를 다시 설치하거나 재시작하고, 설정 → 에이전트(Settings → Agents)에서 연결을 확인하세요.

서비스 없이 실행하기

수명이 짧은 연결이라면 chorus daemon을 포그라운드에 둡니다. 분리(detached) 모드도 사용할 수 있습니다.

chorus daemon -d --agent codex --cwd ~/work/project-a --chorus-only

같은 status, logs, restart, stop 명령으로 관리합니다. 분리 모드를 별도로 작성한 프로세스 관리자와 함께 쓰지 마세요.

운영 상태 점검하기

명령줄과 웹의 상태를 모두 사용합니다.

chorus daemon status를 실행합니다.
chorus daemon logs로 최근 출력을 확인합니다.
설정 → 에이전트(Settings → Agents)에서 기대하는 각 작업 디렉터리가 온라인(Online)인지 확인합니다.
작은 테스트 세션을 시작해, 의도한 디렉터리를 대상으로 하는지 확인합니다.

로그에는 경로, 프롬프트, 명령 출력이 담길 수 있습니다. 공유하기 전에 민감한 값을 제거하세요. 실패한 경우 에이전트 연결 문제 해결로 이어 가세요.