Note: This page is reproduced verbatim from the project's Korean-language source documentation. No English version of this document exists in the source repository yet — only the top-level README has an English translation.

User Manual: Reference

English summary#

Protocol. NDJSON (one line = one JSON), dozens of RPC methods + 13 channel.* methods, dozens of events. The exhaustive lists and the environment-variable table are in the sections below.

Troubleshooting. macOS "damaged and can't be opened" has two causes: a half-install (drag-copy race) or the quarantine attribute — disambiguate with cys doctor app-seal and prefer the "Install cys.app" helper. For a full reset (including Windows WebView2 stored values and leftover department isolates), the source repository points to docs/GUIDE-clean-reset-KR.md — that file does not exist in the current default branch as of this writing, so it is not reproduced here; see the project's docs/ folder on GitHub for the latest state.

The Korean-language detail follows below.

13. 채널 브리지 (Slack·Discord)#

함대의 승인 요청·보고를 외부 메신저로 내보내고, 허가된 발신자의 원격 승인을 받을 수 있습니다.

cys channel --json <액션>   # start·stop·register·inbound·outbound·receipt·ack·
                            # allow·allow-remote-approve·revoke·lockdown·unlock·status

신뢰 방향은 보수적입니다: 발신자 allowlist(allow) · 원격 승인은 별도 허가 (allow-remote-approve) · 즉시 잠금(lockdown) · 발신 내용의 모양 기반 redact(토큰·홈 경로 차단) · 중복/루프 억제 내장.

14. 기록·증거 (recall / attest)#

cys recall "<검색어>"      # 모든 에이전트 터미널 활동의 영속 전사 전문검색(FTS)
cys attest pin            # 전사 해시체인을 외부 보관 (평가자 분리)
cys attest verify         # 사후 변조 대조
cys cost-baseline lock / diff   # 비용·효율 baseline 잠금·전후 비교

전사 보존 기간은 CYS_RECALL_RETAIN_DAYS(기본 30일, 0=무제한)로 제어합니다 — 무한 성장 차단.

15. CLI 레퍼런스#

cys actions를 실행하면 기계가 읽는 자기기술 카탈로그가 나옵니다(clap 정의가 단일 진실원). 아래는 사람용 요약입니다.

분류	명령	설명
기본	`ping` `identify` `actions` `doctor`	데몬 확인·자기 주소·명령 카탈로그·자기진단(`--fix`)
surface	`new-surface` `list` `attach` `read-screen` `resize` `close-surface` `quiesce` `tombstone`	세션 생성·목록·미러링·화면 읽기·크기·닫기(자식 트리 전멸)·주입 보류·묘비
통신	`send` `send-key` `events` `watch`	stdin 주입·키 주입·이벤트 구독·regex 완료 대기
역할·함대	`launch-agent` `boot` `claim-role` `surface-role` `status` `fleet` `set-status` `todo-path`	역할 노드 기동·일괄 부트·역할 등록/조회·관제 보드·자기보고·역할별 TODO 경로
사이클·복구	`cycle-agent` `node-recover` `restore` `reinject` `drain`	컨텍스트 사이클·재기동·조직 복원·지침 재주입·업데이트 전 저장 신호
거버넌스	`run` `ps` `kill` `add-health-rule` `health-rules` `pause` `resume` `gate-check` `queue`	scoped 실행·원장·강제 종료·헬스룰·kill-switch·큐 관리
승인	`feed` `approval`	승인 요청함(push/list/reply)·HMAC signed-prefix 서명(check/sign)
팩·업데이트	`init-pack` `pack-update` `pack-manifest` `license` `pack-repair-channel` `pack-downgrade-to-free` `persona`	팩 설치·무중단 업데이트·매니페스트 방출·pro 라이선스·채널 복구·강등·페르소나
데몬	`daemon install/status/uninstall`	상시 가동 등록·상태·해제
기록·학습	`recall` `attest` `learn` `skill` `cost-baseline`	전사 검색·해시체인 증거·RSI 학습·스킬 라이브러리·비용 baseline
스케줄	`schedule add/list/remove/run`	원샷·반복 발화
채널	`channel <13 액션>`	Slack·Discord 브리지
내부 배관	`usage-register` `usage-report-stdin` `usage-event-stdin`	훅 전용(직접 쓸 일 없음)

16. 환경변수 레퍼런스#

코어(cysd·cys)가 읽는 변수 — 주요#

변수	기본	뜻
`CYS_SOCKET`	`~/.local/state/cys/cys.sock` / win `\\.\pipe\cys`	소켓 경로
`CYS_SHELL`	`$SHELL`→zsh	pane 셀
`CYS_PACK_DIR`	`~/.cys/pack`	팩 위치
`CYS_LOAD_THRESHOLD`	코어수×2	watchdog load 임계
`CYS_PROC_THRESHOLD` / `CYS_DUP_THRESHOLD`	50 / 3	프로세스 수·중복 임계
`CYS_AUTOKILL_DUP`	0	중복 프로세스 자동 kill (opt-in)
`CYS_IDLE_SECONDS`	300	idle 감지
`CYS_TYPING_GUARD_SECS`	3 (0=off)	사람 타이핑 보호
`CYS_CONTEXT_THRESHOLD_PCT`	60	컨텍스트 통보 임계
`CYS_MAX_ACTIVE_WORKERS`	8	워커 동시 상한
`CYS_QUEUE_QUIET_SECS` / `CYS_QUEUE_DEPTH_ALERT`	3 / 5	followup 배달 조건·큐 깊이 경보
`CYS_FEED_REMIND_SECS`	300 (0=off)	승인 적체 재알림
`CYS_MASTER_DEADMAN_SECS`	900 (0=off)	오케스트레이터 무반응 감지
`CYS_AGENT_AUTORESTART`	0	죽은 에이전트 자동 재기동 (3회 상한)
`CYS_RECALL_RETAIN_DAYS`	30 (0=무제한)	전사 보존
`CYS_CONTROL_REDACT`	0	Control Center 세션 PII 가림
`CYS_TODO_DIRS`	—	todo 감시 추가 루트(콜론 구분)
`CYS_NO_AUTOSTART` / `CYS_NO_AUTORESTORE`	—	자동 기동/자동 복원 끄기
`CYS_APPROVAL_SECRET_B64`	자동 생성	승인 서명 시크릿 오버라이드
`CYS_CHANNEL_RETAIN_DAYS` / `CYS_CHANNEL_OUTBOUND_TIMEOUT_SECS`	7 / 30	채널 보존·발신 타임아웃
`CYS_CLAUDE_CTX_WINDOW`	200k (`[1m]`=1M)	컨텍스트 창 크기 힌트

(이 밖에 진단·튜닝용 변수 다수 — CYS_DEBUG, CYS_USAGE_POLL_SECS, CYS_REAP_EXITED*, CYS_CRASH_WINDOW_SECS, CYS_MAX_RESPONSE_BYTES, CYS_ABI_VERIFY 등. 소스 grep env_compat가 전수 목록의 진실원입니다.)

팩 도구가 읽는 변수 (바이너리 아님)#

변수	뜻
`CYS_URL_ALLOW_HOSTS`	외부 URL 허용 도메인 확장(또는 `~/.cys/url-allow-hosts` 파일)
`CYS_WORKER_PROFILE_DIR`	워커 프로필 경로(또는 `~/.cys/worker-profile-dir` 파일)

17. 프로토콜 레퍼런스 (RPC·이벤트)#

NDJSON — 한 줄 = JSON 하나. 요청 {"id","method","params"} → 응답 {"id","ok",result|error}. 서버 push는 events.stream 구독.

RPC 메서드 (v0.12.28 기준 전수)#

system.ping / identify / claim_role / resolve_role / pause / resume / gate_check / topology
surface.create / list / send_text / send_key / read_text / resize / rename / close /
        attach / set_meta / quiesce / wait_for
tombstone.set   events.stream   reinject.mark   status.set
ledger.register / deregister / list / kill
health.add_rule / list_rules
feed.push / reply / list
queue.list / clear
recall.search   attest.pin / verify   approval.check / sign
learn.propose / status / history
schedule.status / run_now
usage.register / report / event
org.status
control.dashboard / hw / analytics / cost_baseline / skills / weekly / alerts /
        sessions / session_detail / session_star
editor.action_catalog / action_info
channel.start / stop / register / inbound / outbound / receipt / ack / allow /
        allow-remote-approve / revoke / lockdown / unlock / status

이벤트 (계열별)#

surface.created/exited/crashed/closed/reaped/zombie_reaped/close_denied/quiescing/input_injected
agent.exited/recovered/restart_blocked/exit_unrecoverable
watchdog.load_high/proc_count_high/duplicate_procs/tick_panic   pane.idle
queue.enqueued/delivered/dropped/depth_high/clear_denied
ledger.registered/killed
feed.item.created/resolved/aging/timeout   feed.backlog_high
health.alert/action
schedule.fired/missed/error/command_done/tick_panic
autopilot.paused/resumed/master_changed/approval_checked/approval_signed
role.claimed/claim_denied   worker.limit_denied
usage.session_registered/updated/register_denied/report_denied/tick_panic
channel.* (bridge.exited·auth.denied·registered·message·outbound.<ch>·lockdown·… 15종)
daemon.started/stopping   acl.denied   context.threshold   status.changed   task.changed
todo.updated   approval.request   approval.stalled   master.deadman   osc.notify

18. 트러블슈팅 · 알려진 한계#

트러블슈팅

증상	조치
macOS "손상되어 열 수 없음"	공증 빌드인지 확인, 우클릭→열기. 미서명 빌드는 quarantine 때문일 수 있음
`cys ping` 실패	앱 실행(데몬 자동 기동) 또는 `cysd` 직접 기동. `cys doctor --fix`
데몬이 두 개 뜸 것 같음	실제로는 불가(중복 기동 거부). 업데이트 후 스쿠 배지가 떠 있으면 클릭해 교대
팩 업데이트가 거부됨	정상일 수 있음 — 서명·신선도·replay 검증은 fail-closed. `cys pack-update --dry-run`·`cys doctor`로 원인 확인
노드에 메시지가 안 들어감	타이핑 가드(사람 입력 직후 3초)·ACL(`acl.denied` 이벤트)·kill-switch(`cys gate-check`) 순서로 확인
Windows SmartScreen 경고	현재 Authenticode 미서명 — "추가 정보→실행"

알려진 한계 (정직성 규약 — 숨기지 않습니다)

macOS에서 sysinfo가 cmdline 전체를 못 읽으면 프로세스명으로 중복 그룹핑(과탐 가능).
cys run 중 Ctrl-C로 CLI가 죽으면 그룹 정리가 watchdog 주기(5초)로 넘어감.
GPU/NPU 실시간은 macOS(Apple Silicon) 전용 — Windows는 CPU/MEM만. NPU는 활용률 공개 API가 없어 실측 전력(W)으로 표시.
단일-UID 신뢰 모델: 승인 서명·자기결재 차단은 같은 계정 내 악성 프로세스에 대한 암호학적 방어가 아니라 탐지·fail-safe 층입니다.
비밀 스캐너는 정적 패턴 매칭 — 난독화·신종 토큰은 못 잡습니다(1차 방어선일 뿐).

취약점 신고는 Security policy를 따라 주세요.

Back: Updates & Pack Operations · Getting Started · Overview

Updated Aug 14, 2026