POST /trigger ───┐
│ ┌────────────────┐
┌───▼───┐ │ tmux session │
...

`curl -fsSL https://raw.githubusercontent.com/andersonaguiar/haiflow/main/install.sh | bash`

설치되지 않은 경우 Bun을 설치하고, `tmux`, `jq`, `claude`, `redis`의 존재 여부를 확인한 후, `haiflow` CLI를 전역적으로 설치하고 Claude Code 훅(hooks)을 연결합니다.

`haiflow init`은 가장 빠르게 작동하는 환경을 구축할 수 있는 방법입니다. 훅을 설치하고, 세션을 시작하며, 스모크 테스트 프롬프트를 발생시키고, 훅이 제대로 연결되지 않은 경우(가장 흔한 무음 실패) 즉시 알려줍니다. 언제든지 상태를 확인하려면 `haiflow doctor` 또는 `GET /doctor`를 실행하세요.

수동으로 진행하는 것을 선호하나요? `haiflow start worker --cwd /path/to/your/project`를 사용하세요.

`HAIFLOW_SKIP_SETUP=1`로 훅 설정을 건너뛸 수 있습니다.
`HAIFLOW_INSTALL_METHOD=npm`으로 npm 레지스트리를 강제할 수 있습니다.

선호한다면 파이프하기 전에 스크립트를 검사할 수 있습니다: `curl -fsSL .../install.sh | less`

또는 CLI를 사용합니다:

`bun install`

Haiflow는 Claude Code hooks를 사용하여 세션 상태를 추적합니다. 설정 명령어는 훅 설정을 `~/.claude/settings.json`에 병합합니다.

: 

`bun run setup`

이 훅들은 가느다란 HTTP 포워더입니다. Claude Code 이벤트를 haiflow 서버로 POST합니다. 서버가 실행되고 있지 않으면 조용히 아무 작업도 하지 않습니다(no-op). 오케스트레이션되지 않은 Claude 세션에는 영향을 주지 않습니다(서버는 알 수 없는 세션 ID를 무시합니다).

`cp .env.example .env`

| 변수 | 기본값 | 설명 |
|---|---|---|
`PORT` | `3333` | HTTP 서버 포트 |
`HAIFLOW_ENV` | `development` | 배포 환경 (`development`/`production`; `NODE_ENV`로 폴백). `production`에서는 보안에 취약한 노출 시 부팅 시 실패하며 약하거나 플레이스홀더 키를 거부합니다. 개발(Dev)은 관대합니다 (터널 필요 없음). |
`HAIFLOW_HOST` | `127.0.0.1` | 바인드 주소. 기본적으로 루프백이므로 원본은 프론트 프록시/터널을 통해서만 도달할 수 있습니다—식별 계층(identity layer)이 포트를 직접 건드려 우회될 수 없습니다. 프로덕션에서 공개 바인드를 하려면 `HAIFLOW_ALLOW_PUBLIC_BIND=true`가 필요합니다. DEPLOYMENT.md를 참조하세요. |
`HAIFLOW_ALLOW_PUBLIC_BIND` | `false` | 프로덕션에서 공개 바인드(`0.0.0.0`/LAN/공개 IP)를 승인합니다—포트를 방화벽으로 보호하고 자체 식별 계층을 실행해야 합니다. 이것이 없으면 프로덕션은 공개적으로 바인딩될 때 시작을 거부합니다.

| 
`HAIFLOW_DATA_DIR` | 
`/tmp/haiflow` | 
세션 상태, 큐 및 응답을 위한 디렉터리 |
`HAIFLOW_PORT` | 
`3333` | 
hook 스크립트가 사용하는 포트 (PORT와 다를 경우 설정) |
`HAIFLOW_API_KEY` | 
— | 필수. 원하는 임의의 문자열 — 이것은 사용자 본인의 비밀이며, 유료 키가 아닙니다. `production` 환경에서는 24자 이상이어야 하며 플레이스홀더가 아니어야 합니다. |
`HAIFLOW_CWD` | 
— | 설정할 경우 모든 세션이 이 cwd를 사용하도록 강제됩니다. `/session/start` 요청 본문의 `cwd` 필드는 무시됩니다 (다를 경우 경고가 기록됨). |
`HAIFLOW_ALLOW_REQUEST_CWD` | 
`true` | 
`false`로 설정하면 `/session/start`는 자체 `cwd`를 설정하려는 요청을 거부합니다 — 이 경우 서버에서 `HAIFLOW_CWD`가 설정되어야 합니다. |
`HAIFLOW_GUARDRAILS` | 
`true` | 
서버 부팅 시 `~/.claude/skills/haiflow-guardrails/SKILL.md`를 설치하고, 모든 새 tmux 세션에 `/haiflow-guardrails`를 주입합니다. 이 스킬은 Claude에게 cwd 외부 경로를 거부하고, 비밀 정보를 읽는 것을 거부하며, 네트워크 유출을 거부하도록 지시합니다. |
`REDIS_URL` | 
`redis://localhost:6379` | 
필수. 이벤트 지속성 및 전송 추적을 위한 Redis URL |
`HAIFLOW_START_READY_TIMEOUT_MS` | 
`15000` | 
`/session/start`가 SessionStart hook이 Claude 세션 ID를 연결하기 위해 기다리는 시간 (밀리초). 실패할 때까지의 시간입니다. (세션이 절대 연결되지 않으면 모든 응답을 조용히 누락하게 되며 — 보통 hooks가 제대로 구성되지 않았음을 의미합니다) |
`HAIFLOW_ALLOW_TRIGGER_CALLBACK` | 
`false` | 
개별 `/trigger` `callbackUrl` 완료 웹훅을 활성화합니다. 기본적으로 비활성화되어 있는데, 임의의 콜백 URL은 SSRF(Server-Side Request Forgery) 취약점이 될 수 있기 때문입니다. |
`HAIFLOW_CALLBACK_ALLOW_HOSTS` | 
— | `callbackUrl`에 대한 선택적 쉼표 구분 호스트 허용 목록. 이것을 설정하면 다른 모든 호스트로의 콜백은 `400`으로 거부됩니다. |
`N8N_API_KEY` | 
— | 워크플로우 통합을 위한 n8n API 키 |
`HAIFLOW_USAGE_ALERT_TOKENS` | 
— | 설정할 경우, 롤링(rolling) 5시간 동안의 토큰 총량이 이 값을 초과하면 `GET /usage/window`가 `alert: true`를 플래그합니다 (경고 전용이며, 절대 제한하지는 않습니다). |
`HAIFLOW_TASK_TIMEOUT_SEC` | 
`0` | 
선택적 하드(hard) 작업별 시간 초과. `0`은 이를 비활성화합니다.

워치독은 시간 초과된 태스크를 플래그합니다 |
`HAIFLOW_WAITING_GRACE_SEC` | 
`120` | 
Claude의 Notification hook에 의해 `waiting`으로 플래그된 세션이 워치독이 작동하기 전에 얼마나 오래 차단 상태로 머무를 수 있는지|
`HAIFLOW_WATCHDOG_RECOVER` | 
`false` | 
`true`일 경우, 워치독은 멈춘(wedged) 세션을 자동으로 복구합니다 (Escape, `timed_out` 표시, drain). 기본값은 경고만 발생시킵니다 |
`HAIFLOW_MAP_MAX_ITEMS` | 
`200` | 
하나의 `POST /map` 호출이 풀(pool)에 걸쳐 분산할 수 있는 최대 항목 수|
`HAIFLOW_MAP_TIMEOUT_SEC` | 
`1800` | 
맵 실행이 리듀서가 부분 결과와 함께 작동하기를 기다리는 시간입니다 (stragglers). 

🔒 전체 위협 모델(threat model), 신뢰 경계(trust boundaries), 심층 방어 계층(defense-in-depth layers) 및 강화 체크리스트(hardening checklist)는 SECURITY.md를 참조하세요.

`HAIFLOW_API_KEY`
필수입니다 — 원하는 아무 문자열이나 선택할 수 있습니다 (예: `openssl rand -hex 32`). 이는 제3자 키나 유료 자격 증명이 아니며, 서버를 보호하기 위해 정의하는 비밀 값일 뿐입니다.

**이것이 중요한 이유:** 인증(auth) 없이는, 서버에 접근할 수 있는 누구나 파일 및 git 액세스 권한을 가지고 실행되는 Claude Code에 임의의 프롬프트를 보낼 수 있습니다. 이는 소스 코드를 읽거나, 파일을 수정하거나, 쉘 명령을 실행하거나, 데이터를 유출하는 것을 의미하며 — 모두 간단한 HTTP 요청을 통해 가능합니다.

에이전트가 디버깅 중 읽은 비밀 값을 출력할 때의 심층 방어(defence-in-depth)로서, haiflow는 모든 아웃바운드 텍스트(응답, 파이프라인 메시지, 웹훅, 채팅 회신)가 외부로 나가기 전에 최선의 노력으로 검열(redaction) 과정을 거칩니다. 이는 알려진 자격 증명 형태(AWS/GitHub/Stripe/Google/Anthropic/OpenAI 키, JWT, Bearer 토큰, 개인 키 블록 등)를 제거하고 각각을 `[REDACTED:type]`로 대체하며 카운트를 기록합니다. 기본적으로 활성화되어 있습니다 (비활성화하려면 `HAIFLOW_REDACT=false`); 이메일은 선택 사항입니다 (`HAIFLOW_REDACT_EMAILS=true`); 자체 패턴을 추가하려면 `HAIFLOW_REDACT_EXTRA`를 사용하세요. 이것은 방화벽(firewall)이 아닌 최선의 노력 DLP(Data Loss Prevention)이며: 인코딩되거나 재구성된 비밀 값은 포착하지 못하며, 에이전트가 작업 디렉토리 내부에 작성하는 파일은 절대 수정하지 않고 오직 아웃바운드 텍스트만 다시 작성합니다.

서버는 이것 없이는 시작을 거부합니다. 모든 API 엔드포인트( `/health` 및 `/hooks/*` 제외)는 `Authorization` 헤더를 필요로 합니다:

`curl -H "Authorization: Bearer your-secret-key" http://localhost:3333/sessions`

Hooks는 로컬에서 실행되는 Claude Code에서 오기 때문에 인증 대상에서 제외됩니다. `/hooks/*`로의 요청은 localhost로 제한됩니다.

haiflow를 원격으로 액세스해야 하는 경우(n8n cloud, 웹훅 등), Cloudflare Zero Trust Access 설정 가이드는 DEPLOYMENT.md를 참조하십시오. 이는 신원 계층을 추가하여 API 키가 도난당하더라도 충분하지 않게 만듭니다.

전체 개발자 문서는 `docs/`에 있으며, 빠른 시작(quickstart), 모든 엔드포인트( `docs/openapi.json`에서 생성된 상호 작용 가능한 플레이그라운드 포함), MCP 서버, n8n 노드, 파이프라인, 워커 풀, 배포 및 보안을 다루는 검색 가능한 Mintlify 사이트입니다. 로컬에서 미리보기를 하려면 다음 명령어를 사용하십시오:

`cd docs && npx mint dev # http://localhost:3000`

전체 API 레퍼런스는 API.md를 참조하십시오: 모든 엔드포인트, 매개변수 및 예시가 포함됩니다. 동일한 내용은 문서 사이트에서도 상호 작용 가능한 레퍼런스로 게시됩니다.

haiflow는 실시간으로 세션을 모니터링하고 제어하기 위한 내장 웹 대시보드를 포함합니다.

{"ts":"2026-03-18T02:35:00Z","level":"info","event":"server_started","port":3333,"auth":true}
{"ts":"2026-03-18T02:35:01Z","level":"info","event":"session_started","session":"worker","cwd":"/app"}
{"ts":"2026-03-18T02:35:02Z","level":"info","event":"trigger_sent","session":"worker","taskId":"task-001"}
...