설정

기본적으로 Collie는 개방형 단일 사용자 모드로 실행됩니다. tailnet에서 해당 URL에 접근할 수 있는 사용자라면 누구나 모든 제어 권한을 갖습니다. 이는 TRUSTED_USER 경고를 발생시킵니다. 접근을 제한하십시오:

# in your .env
COLLIE_TRUSTED_USER=you@example.com           # your tailnet login — Collie rejects anyone else
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net    # only behind your OWN proxy; on a tailnet `collie
                                              # start` discovers this for you

Collie는 ~/.config/collie의 .env 파일에서 설정을 불러옵니다. Herdr가 설치를 관리하는 경우, CLI는 Herdr에 플러그인 설정 디렉터리(일반적으로 ~/.config/herdr/plugins/config/herdr.collie)를 쿼리합니다. 두 경로는 CLI 명령 전반에서 일관되게 해석되므로, 서비스는 여기에 시드된 파일을 읽습니다:

mkdir -p ~/.config/collie && cp .env.example ~/.config/collie/.env

# on a Herdr-managed install, seed Herdr's plugin config dir instead:
cp .env.example "$(herdr plugin config-dir herdr.collie)/.env"

아래 경로는 ~/.config/collie/…을(를) 사용합니다. Herdr로 관리되는 설치 환경에서는 해당 접두사를 $(herdr plugin config-dir herdr.collie)(으)로 바꾸십시오.

Collie는 시작할 때만 .env을(를) 읽습니다. 파일을 수정한 후 collie restart을(를) 실행하십시오.

.env.example 파일에 모든 옵션이 나열되어 있습니다.

여기에는 COLLIE_PORT, COLLIE_SERVE_MODE=http(Headscale 또는 .internal 도메인용), COLLIE_SERVE_PORT(:443 이외의 포트에서 HTTPS를 노출하려는 경우, docs/deployment.md → 단일 호스트의 여러 Collie 참조)이 포함됩니다. CLI는 serve 매개변수를 읽어 bridge로 전달하지 않고 tailscale serve을(를) 구성합니다.

여러 에이전트 홈 디렉터리에서 히스토리를 읽으려면 COLLIE_TRANSCRIPT_ROOT에 쉼표로 구분된 목록을 지정하십시오.

docs/deployment.md은(는) 커스텀 도메인 및 리버스 프록시를 다룹니다. Collie는 동일 출처 정책(SOP)을 적용하므로 커스텀 호스트 이름이나 외부 TLS 종단 장치는 명시적으로 허용 목록에 추가해야 합니다:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

이 설정이 없으면 UI가 빈 페이지로 로드됩니다. 자세한 내용은 문제 해결을(를) 참조하십시오.

자체 슬래시 커맨드

Herdr 플러그인 /fork-in-herdr 또는 사용자 지정 /deploy과 같은 머신 전용 명령은 commands.toml에 넣으십시오. 이 파일은 동일한 리더 및 로드 패턴을 공유하는 네 가지 구성 파일 중 하나입니다.

플래그가 설정된 행은 실행되기 전에 두 번 탭하여 확인해야 합니다. 이 파일들을 편집하면 서비스를 재시작하지 않아도 변경 사항이 적용됩니다. Collie가 특정 행을 거부하면 journalctl --user -u collie -n 20에 줄 번호와 오류가 출력됩니다.

cp commands.toml.example ~/.config/collie/commands.toml

[[commands]]
scope = "omp"                # optional; omit for every pane
command = "/fork-in-herdr"
description = "Fork this conversation into a new herdr tab"

구성된 행과 일치하는 창에는 해당 행만 표시됩니다. ADR 0018에 설명된 대로 가장 범위가 좁은 행이 우선합니다.

확인하려면 창을 열고 /을(를) 탭하십시오. 첫 번째 화면에 구성한 행이 나타납니다.

자체 키 프리셋

commands.toml 옆에 위치한 keys.toml에서 Keys 트레이의 Presets 행을 바꿀 수 있습니다:

cp keys.toml.example ~/.config/collie/keys.toml

[[keys]]
scope = "claude"             # optional; omit for every pane
label = "Yes"
keys = ["Down", "Enter"]     # several chords go out as one batch

창이 정의된 행과 일치하면 기본 Ctrl C/D/U/R/L/Z 버튼(ADR 0018) 대신 사전 설정만 표시됩니다. 트레이의 나머지 부분(Esc, 화살표 키, Enter/Tab/Space, 보조 키, 숫자, F1~F12)은 고정되어 있습니다.

키 조합(chord)은 tmux가 아닌 herdr의 구문을 사용합니다.

확인하려면 창을 열고 Keys → Presets을 눌러 새 버튼을 확인하십시오. Collie가 행을 거부하면 journalctl --user -u collie -n 20에서 오류 세부 정보를 확인하십시오.

자체 빠른 답장

quick-replies.toml에서 Quick 독 문구를 맞춤 설정할 수 있습니다:

cp quick-replies.toml.example ~/.config/collie/quick-replies.toml

[[replies]]
scope = "claude"             # optional; omit for every pane
title = "confirm"
items = ["yes", "no"]        # sent verbatim, one per button

창이 규칙과 일치하면 정의한 그룹이 기본 그룹(ADR 0018)을 대체합니다. 기본 문구는 영어입니다(yes, commit and push).

다른 언어로 실행하거나 approve 같은 단어를 특정 하네스에 보내려면 이 파일을 사용하십시오. scope = "shell"을 설정하면 표준 셸 창을 대상으로 지정하며, 그렇지 않으면 y/n만 수신합니다.

확인하려면 창을 열고 Quick을 눌러 그룹을 확인하십시오. 행을 로드하지 못하면 journalctl --user -u collie -n 20에 오류가 출력됩니다.

사용자 정의 런처

탭 한 번으로 keys.toml 옆의 launchers.toml에서 선언한 명령을 실행합니다.

cp launchers.toml.example ~/.config/collie/launchers.toml

[[launchers]]
command = "htop"             # required; the shell line, typed verbatim into the fresh shell
label = "Top"                # optional; defaults to the first word of command
# cwd = "~/dev/collie"       # optional; absent means "here" — see below

탭한 항목이 열리는 위치는 행이 아니라 어디에서 탭했는지에 따라 달라집니다. 대시보드에서 탭하면 행 이름을 딴 새 Space가 생성됩니다. 위로 스와이프하여 접근하는 전환 시트인 pane에서 탭하면 그 옆에 새 해당 창 자체 Space의 탭이 열립니다.

어느 쪽이든 브리지는 새 셸에 command을 입력하고 Enter 키를 보냅니다. 명령어는 자체 수명을 가집니다. 스스로 종료되는 명령어는 Space나 탭을 함께 닫고, htop는 사용자가 종료할 때까지 유지됩니다.

cwd은 새 Space나 탭이 열리는 위치입니다. 위에서 htop이 하듯이 하나를 고정하면 행을 어디서 탭하든 해당 위치가 우선합니다.

이를 생략하면 "here"를 의미합니다. 대시보드는 홈 디렉터리에서 열고, 창은 해당 창 자체의 cwd에서 엽니다. 즉, cwd가 없는 행은 항상 특정 체크아웃 최상위에 머무는 대신 작업 중인 체크아웃을 따라 이동합니다.

이 파일은 허용 목록입니다. POST /api/launch은 여기에 있는 행과 정확히 일치하는 command만 수락하므로, 휴대폰에서는 이 파일에 없는 항목을 시작할 수 없습니다. 변경 사항은 재시작 없이 즉시 적용되지만, 이미 열려 있는 탭은 다음 로드 시에만 행을 다시 읽습니다.

행은 두 곳에 나타납니다. Spaces 및 Recent처럼 접히는 대시보드의 Launch 섹션과 창에서 위로 스와이프했을 때 나오는 전환 시트의 Launch 섹션입니다. 고정된 행은 홈 디렉터리 기준으로 축약된 폴더 경로를 표시합니다. cwd가 없는 행은 전환기에서 "here"로 표시됩니다(대시보드는 이미 홈을 암시하므로 아무것도 표시되지 않음). 행을 선언하지 않으면 두 섹션 모두 나타나지 않습니다.

pack(여러 머신, 휴대폰 연결용 리드 1대) 환경에서는 각 머신이 이 파일의 자체 복사본을 읽습니다. 행은 리드가 아니라 탭을 실행한 대시보드나 창이 있는 머신에서 실행됩니다.

확인하려면 대시보드를 새로고침하고 herd 아래를 확인하십시오. 행을 로드하지 못하면 journalctl --user -u collie -n 20에 오류가 출력됩니다.

자체 서체

인터페이스 글꼴은 기기별 설정입니다. Settings → Typeface에서 System, Space Grotesk(기본값), Aldrich 중에서 선택할 수 있습니다. 네 번째 설정 파일인 theme.toml에서 커스텀 글꼴을 추가할 수 있습니다:

cp theme.toml.example ~/.config/collie/theme.toml
mkdir -p ~/.config/collie/fonts
cp departure.woff2 ~/.config/collie/fonts/

[[font]]
family = "Departure Mono"    # the picker's label AND the CSS family
file   = "departure.woff2"   # a bare name inside fonts/, woff2 only
weight = "400 700"           # optional

commands.toml 및 기타 설정 파일의 동작과 달리, 사용자 지정 글꼴은 기본 제공 목록을 대체하지 않고 끝에 추가됩니다(ADR 0033). 글꼴은 작업을 트리거하지 않으므로 가려질 대상이 없습니다.

기본 항목 3개 아래에 표시되며, 각 클라이언트 기기에서 자체적으로 선택합니다.

참고할 세 가지 동작은 다음과 같습니다.

• —
  첫 로드 시 레이아웃 이동. 사용자 지정 글꼴은 메트릭이 일치하는 대체 글꼴이 없어 초기 로드 중에 미세한 레이아웃 이동이 발생합니다. 기본 제공 글꼴은 빌드 시점에 대체 글꼴이 생성되므로 이 현상을 방지합니다.
• —
  콜드 로드 지연. 콜드 로드는 짧은 지연 시간과 함께 파일을 가져오며, 캐시된 클라이언트는 즉시 렌더링합니다.
• —
  크롬 UI 전용. 선택한 글꼴은 Collie의 크롬 UI에만 적용됩니다. 터미널 미러, 트랜스크립트, 렌더링된 마크다운은 자체 서체를 유지합니다.
• —
  다음 새로고침 시 즉시 반영. 변경 사항은 재시작할 필요 없이 다음 페이지를 새로고침할 때 적용됩니다. 잘못된 설정은 journalctl --user -u collie -n 20를 통해 확인할 수 있는 오류를 기록합니다.

첨부 파일

메시지 입력란 옆의 클립 아이콘은 호스트로 파일을 업로드하고 메시지에 파일 경로를 삽입합니다.

# in your .env
COLLIE_MAX_UPLOAD_MB=25              # default 10, floor 1, ceiling 512
COLLIE_UPLOAD_EXTRA_TYPES=rb,ex,zig  # bare extensions, no dot

Collie는 소유자 전용 권한으로 <state-dir>/uploads 아래에 파일을 저장하고 초안에 절대 경로를 추가합니다. 터미널은 붙여넣은 파일을 직접 처리할 수 없으므로 에이전트가 해당 경로에서 파일을 읽습니다. 업로드된 파일은 작성된 지 48시간 후에 삭제됩니다.

두 종류의 파일이 허용되며, 서로 다르게 검사됩니다.

이미지 파일은 이름이나 선언된 형식이 아닌 시그니처 바이트로 식별됩니다: png, jpg, gif, webp. SVG는 이미지가 아닌 스크립트를 포함하는 마크업이므로 의도적으로 거부됩니다.

텍스트 파일은 확장자로 식별되며, 바이트 검사로 유효성을 판단합니다. 첫 4 KB에 NUL 또는 비정상적인 제어 바이트가 포함된 파일은 파일명과 관계없이 거부됩니다. 기본 제공 목록은 md, markdown, txt, json, jsonl, yaml, yml, toml, csv, tsv, log, xml, html, htm, css, js, jsx, mjs, cjs, ts, tsx, py, go, rs, sh, bash, sql, diff, patch입니다.

참고. COLLIE_UPLOAD_EXTRA_TYPES 항목은 텍스트 형식만 추가합니다. 이미지는 비교할 시그니처가 필요하므로 이 방식으로 바이너리 형식을 추가할 수 없습니다.

COLLIE_MAX_UPLOAD_MB 값을 올리면 두 가지 다른 수치도 함께 증가합니다. 브릿지는 업로드 크기를 측정하기 전에 전체 내용을 메모리에 읽어 들이므로, 제한 값이 크고 여러 업로드가 동시에 발생하면 그만큼 많은 메모리를 사용합니다. 또한 런타임의 본문 제한은 업로드 경로뿐 아니라 모든 경로에 적용되므로, 제한 값을 올리면 큰 본문이 모든 핸들러에 도달할 수 있으며 해당 핸들러 자체 제한에 의해 거부됩니다. 48시간이 지나기 전에는 아무것도 삭제되지 않으므로, 업로드 디렉터리에는 최대 이틀 동안 전송된 데이터가 보관됩니다. 기본으로 올리지 말고 필요한 경우에만 값을 올리십시오.

pack 환경에서는 두 설정이 머신별로 적용되며, 파일을 저장하는 머신이 해당 설정을 적용합니다. 리드는 업링크를 절약하기 위해 전달 전에 초과 크기의 본문을 거부하지만, 자체 설정값을 기준으로 거부합니다. 모든 멤버에 동일한 값을 설정하십시오. 그렇지 않으면 피어가 리드가 통과시킨 데이터를 거부할 수 있습니다.

다중 세션

기본적으로 단일 Collie 인스턴스가 발견된 모든 Herdr 세션을 처리합니다.

기본값인 COLLIE_MULTI_SESSION=on은(는) 설정 루트 아래에 있는 이름이 지정된 모든 Herdr 세션을 검색하여 제공하며, 헤더에서 전환할 수 있습니다. COLLIE_MULTI_SESSION=off을(를) 설정하면 기본 세션만 제공됩니다. 검색된 모든 세션은 비공개 또는 샌드박스 세션을 포함하여 동일한 URL을 통해 접근할 수 있습니다. 보안에서는 이 동작을 주의해야 할 위험 요소로 명시하고 있습니다.

다크 모드 / 라이트 모드

참고. Collie는 기본적으로 휴대폰의 화면 모드 설정을 따릅니다.

고정하려면 Settings → Appearance을 열고 System, Light 또는 Dark를 선택하십시오. 설정은 브리지가 아니라 브라우저의 기기별에 저장됩니다. 노트북이 OS를 따르는 동안 휴대폰은 다크 모드를 유지할 수 있습니다. 설정 환경설정은 동일한 기기에서 새로고침하거나 PWA를 재설치해도 유지됩니다.

터미널 미러는 의도적으로 다르게 동작합니다

미러는 항상 어두운 배경에 렌더링됩니다. 라이트 모드는 개별 span의 색상을 다시 지정하는 대신 전체 요소를 반전시킵니다.

에이전트는 어두운 배경에 맞춰 조정된 절대 24비트 색상 코드(38;2;r;g;b)를 출력하며, 다운스트림 파서는 이를 안정적으로 재매핑할 수 없습니다. 흰색 위에 직접 렌더링하면 대부분의 에이전트 출력 대비율이 3:1 미만으로 떨어집니다. 반전 처리는 의도된 대비를 보존합니다. 측정값은 ADR 0002에 문서화되어 있습니다.

이 구현에는 두 가지 실제적인 영향이 있습니다.

• —
  에이전트가 다크 테마를 사용하도록 설정하십시오. Claude Code, codex, opencode, pi의 기본값입니다. 에이전트가 라이트 테마를 사용하면 밝은 배경용 어두운 색상 값을 출력하므로, 두 모드 모두에서 Collie 내 가독성이 떨어집니다. 이는 Collie 자체가 아니라 에이전트 출력에서 비롯된 문제입니다.
• —
  라이트 모드에서는 Diff 및 강조 표시된 행이 어두운 블록으로 렌더링됩니다. 대비는 그대로 유지되지만 시각적 무게감이 반전됩니다.

참고. iOS에 설치된 라이트 모드에서는 상태 표시줄 텍스트가 흰색으로 유지되어 배경과 겹쳐 보일 수 있습니다. iOS는 웹 앱이 이 값을 동적으로 업데이트하도록 허용하지 않습니다. 이 제한을 피하려면 설치된 PWA 대신 브라우저에서 Collie를 직접 실행하십시오.

Zen mode

참고. Zen 모드는 기본적으로 꺼져 있습니다.

Settings → Zen mode에서 활성화할 수 있습니다(브라우저의 기기별로 저장됨). 활성화하면 Find 및 History 옆의 ⋮ 아래에 있는 창 메뉴에 Zen mode 옵션이 추가됩니다. 이 옵션을 탭하면 헤더, 탭 및 창 스트립, 에이전트 statusline, composer dock 등 모든 Collie UI 요소가 숨겨집니다. 터미널 미러만 계속 표시됩니다. 오른쪽 상단 모서리의 플로팅 버튼이나 Escape 키를 누르면 인터페이스가 복원됩니다.

Zen 모드는 일시적입니다. 설정은 유지되지만 창을 전환하거나 페이지를 새로고침하면 활성 상태가 재설정됩니다. 창은 항상 기본 크롬과 함께 열립니다.

터미널 미러는 Zen 모드에서도 폴링을 계속하며, 대화형 버퍼 요소는 계속 작동합니다. 프롬프트 버튼, "Load older", "Show entire history" 컨트롤은 크롬이 아닌 콘텐츠 스트림의 일부이므로 계속 사용할 수 있습니다.

Language

Collie 인터페이스는 6개 언어로 제공됩니다. Settings → Language에서 설정하십시오.

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文

선택 사항은 기기별로 브라우저에 로컬로 저장됩니다. 터미널 미러는 번역되지 않은 상태로 유지됩니다. 에이전트의 원시 출력을 표시하며, 빠른 응답, 메뉴 레이블, 키 캡은 기본 화면이나 키보드 이름과 일치합니다.