pilot-protocol/pilotprotocol오버레이 네트워크 프로토콜로, AI 에이전트에 영구 주소, 인증된 암호화 터널, UDP 기반 신뢰 모델을 제공합니다. NAT 트래버설, 피어투피어 메시징, Node.js, Python 및 Swift용 SDK를 포함합니다.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/aca1679f7d00fe2469f0e9f72a440a9bcbe7d0448446e1d15a79f0669bdc3d18.png" alt="Pilot Protocol" width="200">
</p>
<h1 align="center">Pilot Protocol</h1>
<p align="center">
<strong>AI 에이전트를 위한 네트워크 스택.</strong><br>
주소. 포트. 터널. 암호화. 신뢰.
</p>
<p align="center">
<a href="https://pilotprotocol.network/docs/"><strong>문서</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/SPEC.md"><strong>와이어 명세</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>백서</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>IETF 초안</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>에이전트 스킬</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo (실시간 대시보드)</strong></a>
</p>
<br>
<p align="center">
<img src="https://img.shields.io/badge/lang-Go-00ADD8?logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/core-stdlib-brightgreen" alt="Core uses Go standard library only">
<img src="https://img.shields.io/badge/encryption-AES--256--GCM-blueviolet" alt="Encryption">
<img src="https://img.shields.io/badge/tests-1048%20pass-success" alt="Tests">
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><img src="https://img.shields.io/badge/IETF-Internet--Draft-blue" alt="IETF Internet-Draft"></a>
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License">
</p>
---
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/290649ca3b8051e074e6f0b5f3bda2c43eeeb40e86686f8767bf9734269912cc.gif" alt="Pilot Protocol Demo — two agents: install, trust, data exchange" width="960">
</p>
인터넷은 인간을 위해 만들어졌다. AI 에이전트에게는 주소도, 신원도, 접근할 방법도 없다. Pilot Protocol은 에이전트에게 인터넷이 기기에게 부여한 것을 제공하는 오버레이 네트워크다: **영구 주소, 인증된 암호화 채널, 그리고 신뢰 모델** -- 이 모든 것이 표준 UDP 위에 계층화되어 있다.
에이전트는 검색과 NAT 통과를 위해 랑데부 서비스에 등록한다. 애플리케이션 데이터는 직접 경로를 통해 피어 간에 직접 흐른다. NAT 홀 펀칭이 실패할 경우(예: 대칭 NAT), 비컨이 여전히 종단 간 암호화된 트래픽을 폴백으로 중계한다. 이것은 API가 아니다. 프레임워크도 아니다. 인프라다.
---
## 문제
오늘날 에이전트는 중앙화된 API를 통해 대화한다. 모든 메시지가 플랫폼을 거친다 -- 플랫폼은 모든 트래픽을 보고, 접근을 통제하며, 단일 장애점이 된다.
```mermaid
graph LR
A1[Agent A] -->|HTTP API| P[Platform / Cloud]
A2[Agent B] -->|HTTP API| P
A3[Agent C] -->|HTTP API| P
style P fill:#f66,stroke:#333,color:#fff
style A1 fill:#4a9,stroke:#333,color:#fff
style A2 fill:#4a9,stroke:#333,color:#fff
style A3 fill:#4a9,stroke:#333,color:#fff
```
Pilot Protocol는 플랫폼을 데이터 경로에서 제거합니다. 경량 **rendezvous** 서비스가 검색과 NAT 트래버설을 처리하지만, 에이전트들이 서로를 찾으면 인증되고 암호화된 터널을 통해 직접 통신합니다:
```mermaid
graph LR
A1[Agent A<br/><small>0:0000.0000.0001</small>] <-->|Encrypted UDP Tunnel| A2[Agent B<br/><small>0:0000.0000.0002</small>]
A1 <-->|Encrypted UDP Tunnel| A3[Agent C<br/><small>0:0000.0000.0003</small>]
A2 <-->|Encrypted UDP Tunnel| A3
A1 -.->|discovery| RV[Rendezvous]
A2 -.->|discovery| RV
A3 -.->|discovery| RV
style A1 fill:#4a9,stroke:#333,color:#fff
style A2 fill:#4a9,stroke:#333,color:#fff
style A3 fill:#4a9,stroke:#333,color:#fff
style RV fill:#888,stroke:#333,color:#fff
```
---
## 에이전트가 얻는 것
```bash
pilotctl info # show your address, hostname, peer count
pilotctl set-hostname my-agent # claim a name other agents can resolve
pilotctl find agent-alpha # resolve a public demo peer
pilotctl ping agent-alpha # round-trip over the encrypted tunnel
pilotctl bench agent-alpha # 1 MB echo benchmark
```
신뢰할 수 있는 피어가 확보되면, 에이전트 간 메시징은 포트 1001의 데이터 교환 서비스를 사용합니다:
```bash
# Send a structured message (waits for reply by default)
pilotctl send-message other-agent --data "hello"
# Read messages delivered to your inbox
pilotctl inbox
# Read a specific message
pilotctl inbox read <id>
```
하위 수준의 원시 포트 메시징의 경우:
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
모든 CLI 명령은 구조화된 출력을 위한 `--json`을 지원합니다. 전체 범위는 [CLI 레퍼런스](https://pilotprotocol.network/docs/cli-reference)를 참조하세요.
<details>
<summary><strong>JSON 출력 예시</strong></summary>
```json
$ pilotctl --json info
{"status":"ok","data":{"address":"0:0000.0000.0005","node_id":5,"hostname":"my-agent","peers":3,"connections":1,"uptime_secs":3600}}
$ pilotctl --json find other-agent
{"status":"ok","data":{"hostname":"other-agent","address":"0:0000.0000.0003"}}
$ pilotctl --json recv 1000 --count 1
{"status":"ok","data":{"messages":[{"seq":0,"port":1000,"data":"hello","bytes":5}]}}
$ pilotctl --json find nonexistent
{"status":"error","code":"not_found","message":"cannot find \"nonexistent\" — hostname not found or no mutual trust","hint":"establish trust first: pilotctl handshake nonexistent \"reason\""}
```
</details>
---
## 프로그래밍 방식 접근 (SDK)
데몬이 실행 중이면 CLI 대신 SDK를 통해 에이전트와 프로그래밍 방식으로 상호작용할 수 있습니다. 세 가지 SDK 모두 Unix 소켓 IPC를 통해 로컬 Pilot 데몬과 통신하며, 원하는 언어로 전체 에이전트 기능 — 핸드셰이크, 신뢰, 전송, 수신, 스트림, 게이트웨이 — 을 제공합니다.
| 언어 | 패키지 | 빠른 시작 |
|----------|---------|------------|
| **Node.js / TypeScript** | [npm의 `pilotprotocol`](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — [sdk-node README](https://github.com/pilot-protocol/sdk-node) 참조 |
| **Python** | [PyPI의 `pilotprotocol`](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — [sdk-python README](https://github.com/pilot-protocol/sdk-python) 참조 |
| **Swift / iOS / macOS** | [GitHub의 `pilotprotocol`](https://github.com/pilot-protocol/sdk-swift) | `Package.swift`를 통해 추가 — [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) 참조 |
`daemon start` 이후의 최소 Node.js 첫 쿼리 예제:
```js
import { createPilot, createAgent } from 'pilotprotocol';
const pilot = await createPilot();
const conn = await pilot.handshake('agent-alpha', 'hello');
await conn.trust();
// Send a message
await conn.send(3000, Buffer.from('ping'));
// Receive on any port
const msgs = await conn.recv(3000, { count: 1, timeout: 10 });
console.log('Received:', msgs[0].data.toString());
```
각 SDK의 README에서 전체 API 문서, 스트리밍 예제, 플랫폼별 설정(iOS 시뮬레이터, PyPI extras 등)을 확인하세요.
## 하이라이트
<table>
<tr>
<td width="50%" valign="top">
**주소 지정**
- 48비트 가상 주소 (`N:NNNN.HHHH.LLLL`)
- 잘 알려진 할당이 있는 16비트 포트
- 호스트 이름 기반 검색
**전송**
- 신뢰할 수 있는 스트림 (TCP 상응)
- 슬라이딩 윈도우, SACK, 혼잡 제어 (AIMD)
- 흐름 제어 (광고된 수신 윈도우)
- Nagle 병합, 자동 분할, 제로 윈도우 프로빙
- NAT 통과: STUN 검색, 홀 펀칭, 릴레이 폴백
</td>
<td width="50%" valign="top">
**보안**
- 인증된 키 교환 (Ed25519 서명 X25519 + AES-256-GCM)
- 터널 세션에 바인딩된 Ed25519 신원 키
- 노드는 기본적으로 비공개
- 상호 신뢰 핸드셰이크 프로토콜 (서명됨, 레지스트리를 통한 릴레이)
**운영**
- 핵심 프로토콜: Go 표준 라이브러리만 사용
- 내장 서비스가 포함된 단일 데몬 바이너리
- 구조화된 JSON 로깅 (`slog`)
- 모든 상태에 대한 원자적 영속성
- 핫 스탠바이 레지스트리 복제
</td>
</tr>
</table>
---
## 아키텍처
```mermaid
graph LR
subgraph Local Machine
Agent[Your Agent] -->|commands| CLI[pilotctl]
CLI -->|Unix socket| D[Daemon]
D --- E[Echo :7]
D --- DX[Data Exchange :1001]
D --- ES[Event Stream :1002]
end
D <====>|UDP Tunnel<br/>AES-256-GCM + NAT traversal| RD
subgraph Remote Machine
RD[Remote Daemon] -->|Unix socket| RC[pilotctl]
RC -->|commands| RA[Remote Agent]
RD --- RE[Echo :7]
RD --- RDX[Data Exchange :1001]
RD --- RES[Event Stream :1002]
end
D -.->|register + discover| RV
RD -.->|register + discover| RV
subgraph Rendezvous
RV[Registry :9000<br/>Beacon :9001]
end
```
에이전트는 Unix 소켓을 통해 로컬 **데몬**과 통신합니다. 데몬은 터널 암호화, NAT 통과, 패킷 라우팅, 혼잡 제어, 내장 서비스를 처리합니다. 데몬은 노드 등록, 피어 검색, NAT 홀 펀칭을 위해 **렌데즈부** 서버(레지스트리 + 비컨)와의 연결을 유지합니다. 터널이 설정되면 데이터는 데몬 간에 직접 흐릅니다 -- 렌데즈부는 데이터 경로에 없습니다. 단, 비컨이 대칭 NAT 뒤에 있는 피어의 트래픽을 중계해야 하는 경우는 예외입니다(중계된 트래픽은 종단 간 암호화된 상태로 유지됩니다).
공용 렌데즈부는 `34.71.57.205:9000`에서 제공되며, `rendezvous -registry-addr :9000 -beacon-addr :9001`로 직접 실행할 수도 있습니다.
연결 수명 주기 세부 사항, 게이트웨이 브리징, NAT 통과 전략은 [전체 문서](https://pilotprotocol.network/docs/)를 참조하세요.
---
## 데모
공용 데모 에이전트(`agent-alpha`)가 자동 수락이 활성화된 상태로 네트워크에서 실행 중입니다:
```bash
# 1. Install
curl -fsSL https://pilotprotocol.network/install.sh | sh
# 2. Start the daemon
pilotctl daemon start --hostname my-agent --email [email protected]
# 3. Request trust (auto-approved within seconds)
pilotctl handshake agent-alpha "hello"
# 4. Wait a few seconds, then verify trust
pilotctl trust
# 5. Start the gateway (maps the agent to a local IP)
sudo pilotctl extras gateway start --ports 80 0:0000.0000.0004
# 6. Open the website
curl http://10.4.0.1/
```
다음과 같이 ping 및 벤치마크를 수행할 수도 있습니다:
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
## 설치
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
설치 중 호스트 이름과 이메일 설정:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP가 차단되어 있거나, 유일한 탈출구가 HTTPS 프록시인 경우**(Meta Muse와 같은 호스팅 에이전트 샌드박스, 잠긴 VM)? 일반 설치가 작동합니다:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
새 설치에서는 transport `auto`를 사용합니다. 데몬은 시작 시 UDP로 비컨을 한 번 프로브하고(UDP가 작동하면 왕복 한 번, 작동하지 않으면 최대 ~1.5초), 응답이 없지만 compat 비컨이 TCP 443으로 응답하는 경우(라이브 비컨이 `426 Upgrade Required`로 응답하는 TLS 요청) **compat** 모드로 실행됩니다 — 레지스트리는 `registry.pilotprotocol.network:443`에서 TLS로, 비컨은 `beacon.pilotprotocol.network:443`에서 WSS로. 프록시가 구성되어 있고 그 검사를 거부하는 경우(잘못되었거나 오래된 자격 증명: `407`, `403`, 또는 프록시에 연결할 수 없음), 프록시를 우회하여 직접 연결로 폴백하는 대신 그대로 compat로 실행되며, 레지스트리 dial은 프록시의 응답을 명시합니다. `pilotctl daemon start`는 "did not become ready"만 출력하는 대신 힌트와 함께 데몬의 마지막 프록시 오류를 출력합니다. 둘 다 응답하지 않고 프록시가 관여하지 않는 경우(아직 네트워크 없음, 비컨 장애)에는 이전과 마찬가지로 UDP에 머무릅니다. compat 모드에서 데몬은 `$HTTPS_PROXY` / `$ALL_PROXY`를 통해 터널링하며(`$NO_PROXY`를 준수), 프록시에 호스트 이름으로 `CONNECT`를 요청하므로 Pilot 호스트에 대한 오염된 로컬 DNS는 문제가 되지 않습니다. `pilotctl` 자체의 레지스트리 명령(`lookup`, 자동 핸드셰이크 검사, `recovery`)은 데몬을 따릅니다: compat로 실행될 때(또는 명시적 프록시 URL이 있을 때)는 프록시를 통해, UDP로 실행될 때는 직접. 데몬이 실행 중이 아니고 transport가 구성되지 않은 경우에는 프록시를 먼저 시도하고 직접 연결을 두 번째로 시도합니다. UDP 프로브를 건너뛰려면 compat를 명시적으로 선택하세요: `sh -s -- --transport compat`, `pilotctl config --set transport=compat`, 또는 `pilotctl daemon start --transport compat`.
- **root, systemd 또는 launchd가 필요하지 않습니다.** 프록시 변수가 있는 셸에서 `pilotctl daemon start`로 데몬을 시작하세요. systemd가 없는 컨테이너나 VM에서는 설치 프로그램이 root로도 실행되며(호스팅 샌드박스의 에이전트 사용자); 일반 호스트에서는 `PILOT_ALLOW_ROOT=1`이 아니면 여전히 root를 거부합니다.
- **컨테이너에서는 데몬에 init 프로세스를 제공하세요.** 앱은 데몬화하는 서버(redis, postgres)를 시작합니다. 데몬화된 서버는 PID 1에 넘겨지고, 중지되면 PID 1이 수거할 때까지 좀비(`ps`에서 `Z`)로 남습니다. PID 1 자체인 `pilot-daemon`은 수거하지 않으므로 좀비가 누적되어 컨테이너의 PID 제한에 포함됩니다. 컨테이너를 `docker run --init`으로 실행하거나(Compose: `init: true`), [tini](https://github.com/krallin/tini)를 entrypoint로 지정하거나(`ENTRYPOINT ["tini", "--", "pilot-daemon"]`), Kubernetes에서는 `shareProcessNamespace: true`를 설정하세요(ECS: `initProcessEnabled`). 데몬은 자신이 PID 1일 때 시작 시 경고를 기록합니다. 경고가 없다고 해서 셸 스크립트처럼 수거하지 않는 다른 프로세스가 PID 1인 경우까지 문제가 없다는 증거는 아닙니다. 데몬은 고아 프로세스를 직접 수거하지 않습니다. 프로세스 내에서 그렇게 하면 감독하는 앱의 종료 상태도 가져가게 되기 때문입니다.
- **자격 증명이 있는 프록시:** `ps`에 노출되지 않게 하세요 — `HTTPS_PROXY` / `PILOT_PROXY`를 export하거나, `pilotctl daemon start --proxy http://user:pass@host:port`를 사용하세요(pilotctl은 자격 증명이 포함된 URL을 명령줄이 아닌 환경으로 데몬에 전달합니다). 셸의 변수를 보지 못하는 systemd/launchd 서비스의 경우 저장하세요: `pilotctl config --set proxy=http://user:pass@host:port` (config.json은 0600).
- **교체되는 프록시 자격 증명**(Meta Muse는 `HTTPS_PROXY`의 자격 증명을 몇 분마다 교체): 장기 실행 데몬은 시작할 때의 자격 증명을 계속 사용하게 되어, 새 연결은 `407 Proxy Authentication Required`로 실패하기 시작하는 반면 기존 터널은 유지됩니다("node online, apps broken"). 데몬에 현재 프록시 URL을 출력하는 명령을 제공하세요 — config.json의 `proxy_cmd`, `$PILOT_PROXY_CMD`, `-proxy-cmd` 또는 `pilotctl daemon start --proxy-cmd` — 그러면 60초가 지난 후 그리고 프록시가 자격 증명을 거부할 때마다(407, 또는 Muse의 깨진 "malformed HTTP status code" 응답) 다시 실행하여 새 자격 증명으로 해당 연결을 한 번 재시도합니다(레지스트리, compat 비컨, HTTP 클라이언트 모두, common의 `netproxy` refresh를 통해); 재시작이 필요 없습니다. 데몬이 시작하는 앱은 현재 자격 증명을 추가하는 데몬 내의 루프백 릴레이를 통해 프록시에 도달하므로 교체 전반에 걸쳐 계속 작동합니다. pilotctl 자체의 레지스트리 명령도 동일한 명령을 사용합니다. `HTTPS_PROXY` 또는 `https_proxy`에 자격 증명이 있는 systemd 없는 Linux 컨테이너/VM에서, `pilotctl daemon start`는 `proxy_cmd`가 구성되지 않은 경우 새 bash의 `$https_proxy`(또는 자격 증명이 있는 것이 그것뿐일 때는 `$HTTPS_PROXY`)를 출력하는 `PILOT_PROXY_CMD`를 데몬에 전달하며, 설치 프로그램은 동일한 명령을 config.json에 저장합니다. 그 외의 경우: `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. 이것이 없으면 실패하기 시작할 때 새 셸에서 데몬을 재시작하세요.
- **transport와 프록시의 우선순위:** 명령줄 플래그, 그다음 `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, 그다음 `config.json`(`transport`, `proxy`, `proxy_cmd`), 그다음 기본값(pilotctl 및 설치된 systemd/launchd 서비스의 경우 `PILOT_TRANSPORT_DEFAULT=auto`를 통한 `auto`; 순수 `pilot-daemon`의 경우 `udp`; 프록시 `auto`). `auto`는 config.json에 절대 저장되지 않으므로, 이전 릴리스(`--version`, `pilotctl update --pin`)를 재설치해도 읽을 수 없는 것이 남지 않습니다. 직접 저장한 경우, 이를 지원하지 않는 데몬에서는 둘 다 `udp`로 다시 씁니다. `-proxy`는 `auto`, `off`(`none`, `direct`도 가능) 또는 `http://` / `https://` URL을 허용하며, 그 외는 오류입니다. 루프백 대상(로컬 웹훅, 사이드카)은 절대 프록시로 전송되지 않습니다. 레지스트리 dial이 프록시를 통해 이루어질 때(compat, 또는 모든 transport에서 명시적 프록시 URL), 기본 raw-TCP 레지스트리는 TLS를 통한 `registry.pilotprotocol.network:443`으로 대체됩니다. CONNECT 프록시는 포트 443만 전달하기 때문입니다.
- **샌드박스에 CA 번들이 없나요?** `SSL_CERT_FILE=/path/to/ca-certificates.crt`(또는 `SSL_CERT_DIR`)로 Go에 지정하세요 — `pilotctl daemon start`는 둘 다 전달합니다. 대신 레지스트리를 고정할 수 있습니다: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>`(또는 `pilotctl config --set registry_fingerprint=...`), 이는 `registry_trust=pinned`를 선택합니다. WSS 비컨에는 fingerprint 옵션이 없으므로 CA 번들이 필요합니다.
<details>
<summary><strong>설치 프로그램이 하는 일</strong></summary>
- 플랫폼 감지(linux/darwin, amd64/arm64)
- 최신 릴리스에서 미리 빌드된 바이너리 다운로드(Go가 있으면 소스에서 빌드하는 것으로 폴백)
- `pilot-daemon`, `pilotctl`, `pilot-updater`를 `~/.pilot/bin`에 설치(릴리스 tarball에는 이 세 가지가 포함되며, 게이트웨이는 선택적 추가 요소로 핵심 설치의 일부가 아님)
- `~/.pilot/bin`을 PATH에 추가
- 공용 랑데부 서버가 미리 구성된 `~/.pilot/config.json` 작성
- 데몬과 자동 업데이터를 위한 시스템 서비스 설정(**Linux**: systemd, **macOS**: launchd)
- 자동 업데이터는 백그라운드에서 실행되며, 매시간 새 릴리스를 확인하고 업데이트를 자동으로 적용
**제거:** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**소스에서** (Go 1.25+ 필요): `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
Pilot에는 로컬 IPC 앱을 설치하고 호출하기 위한 내장 앱 스토어가 포함되어 있습니다:
```bash
pilotctl appstore catalogue # browse available apps
pilotctl appstore view io.pilot.cosift # inspect before installing
pilotctl appstore install io.pilot.cosift # install an app
pilotctl appstore list # list installed apps
pilotctl appstore call io.pilot.cosift cosift.help '{}' # discover methods + latencies
pilotctl appstore call io.pilot.cosift cosift.search '{"q":"raft consensus","k":"5"}'
```
앱은 서명되며(ed25519), 설치 시와 매번 스폰될 때마다 검증됩니다. 데몬이 모든 앱 간 호출을 중개합니다 — 앱은 자신의 매니페스트에 선언한 메서드를 통해서만 접근될 수 있습니다. 앱 빌드, 서명, 게시에 대해서는 [App Store 문서](https://pilotprotocol.network/docs/app-store)를 참조하세요.
---
## 테스트
```bash
go test -parallel 4 -count=1 ./tests/
```
`-parallel 4` 플래그는 필수입니다 — 무제한 병렬 처리는 포트를 고갈시키고 다이얼 타임아웃을 유발합니다.
---
## 프라이버시 제어 및 동의
네 가지 기능이 **기본적으로 켜진 상태**로 제공됩니다. 각각은 Pilot을 개선합니다 — 당신을 위해서, 개발자를 위해서, 또는 네트워크를 위해서 — 하지만 각각은 받아들이기 전에 이해해야 할 비용을 수반합니다. 어느 것도 핵심 메시징, 라우팅, 암호화에 영향을 주지 않습니다.
전체 문서, 위험 프로필, 기능별 명령어: **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### 텔레메트리 — 위험: 낮음
**하는 일.** 앱을 탐색하거나 설치할 때, 서명된 이벤트(앱 ID + 동작)가 `telemetry.pilotprotocol.network`로 전송됩니다.
**누구에게 도움이 되는가.** 앱 개발자는 실제로 무엇이 사용되는지에 대한 신호를 얻고, 카탈로그는 방치된 앱보다 품질 좋은 앱을 부각시키며, 당신은 광고가 아닌 실제 사용량을 기반으로 개선되는 큐레이션된 스토어의 혜택을 받습니다.
**당신이 받아들이는 것.** 텔레메트리 서버는 앱 ID, 동작 유형, 그리고 당신의 Ed25519 키로부터의 서명을 수신합니다(`-email`로 등록하지 않은 경우 가명). TLS 연결 중에는 당신의 IP가 보입니다. 메시지 내용이나 대화 데이터는 절대 전송되지 않습니다.
**옵트아웃하려면:**
```json
{"consent": {"telemetry": false}}
```
`~/.pilot/config.json`에 설정합니다. 텔레메트리 클라이언트는 완전한 no-op이 됩니다 — 다이얼 없음, 고루틴 없음. CLI 명령에 즉시 적용됩니다.
**누가 옵트아웃해야 하는가:** 엄격한 무텔레메트리 정책을 가진 사용자, 고민감도 배포 환경, 또는 모든 아웃바운드 텔레메트리가 바람직하지 않은 자동화 파이프라인.
---
### 브로드캐스트 — 위험도: 중간
**하는 일.** 네트워크 관리자는 인증된 단일 데이터그램을 네트워크의 모든 에이전트에 동시에 보낼 수 있습니다. 여러분의 데몬은 관리자 토큰을 확인하고 페이로드를 여러분의 에이전트로 전달합니다.
**누구에게 도움이 되는가.** 플릿 운영자는 단일 명령으로 모든 에이전트를 조정할 수 있습니다 — 구성 새로고침, 롤링 재시작, 사고 대응 — O(N)개의 개별 메시지 없이. 대규모 피어 메시에서 유일한 O(1) 조정 메커니즘입니다.
**여러분이 받아들이는 것.** 네트워크의 관리자 토큰을 보유한 모든 주체가 여러분의 에이전트에 임의의 데이터를 전달할 수 있습니다. 토큰의 보안이 한계입니다: 토큰이 유출되거나 신뢰하지 않는 누군가가 보유하고 있다면, 공격자가 여러분의 에이전트에 도달할 수 있습니다.
**옵트아웃하려면:**
```json
{"consent": {"broadcasts": false}}
```
수신 데이터그램은 에이전트에 도달하기 전에 조용히 폐기됩니다. 변경 사항을 적용하려면 데몬을 재시작하세요.
**누가 옵트아웃해야 하는가:** 솔로 사용자(플릿도, 관리자도 없음 — 이 기능은 당신에게 아무 이점도 없으며 아무 대가 없이 공격 표면을 받아들이는 셈입니다). 관리자를 알지 못하거나 신뢰하지 않는 네트워크에 참여하는 사용자.
---
### 리뷰 — 위험: 낮음
**기능.** `pilotctl send-message` 호출의 약 5% 후에 stderr에 리뷰를 권유하는 프롬프트가 나타납니다. `pilotctl appstore call` 호출의 약 5% 후에는 출력이 해당 앱에 대한 리뷰 프롬프트로 대체됩니다. 명시적인 `pilotctl review <subject>` 명령은 리뷰를 직접 전송합니다.
**누구에게 도움이 되는가.** 커뮤니티 리뷰는 설치 전에 품질 신호를 드러냅니다. 앱 개발자는 직접적인 피드백을 받습니다. 리뷰 점수는 카탈로그 순위를 결정합니다 — 좋은 앱은 가시성을 얻고, 망가진 앱은 우선순위가 낮아집니다.
**당신이 받아들이는 것.** 리뷰 텍스트는 전적으로 사용자가 작성하며 옵트인 방식입니다. 주요 운영상 위험은 5% 가로채기가 스크립트에서 stdout을 손상시킬 수 있다는 점입니다.
```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4
```
**옵트아웃하려면:**
```json
{"consent": {"reviews": false}}
```
프롬프트 없음, 가로채기 없음, 전송되는 데이터 없음. 즉시 적용됩니다.
**누가 옵트아웃해야 하는가:** stdout이 깨끗하게 유지되어야 하는 자동화나 파이프라인에서 `pilotctl`을 실행하는 사용자. 정상 작동 중에 원치 않는 프롬프트를 받고 싶지 않은 사용자.
---
### 스킬 주입 — 위험도: 중간
**하는 일.** 데몬은 지원되는 에이전트 툴체인(Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes)의 설정 디렉터리에 `SKILL.md`와 하트비트 지시문을 작성하여, 해당 에이전트들에게 `web_search`나 `curl`로 폴백하기 전에 Pilot 도구를 먼저 사용하라고 지시합니다.
**누구에게 도움이 되는가.** 제로 구성 통합을 얻습니다 — 에이전트는 피어 메시징, 전문가 쿼리, 앱 호출에 Pilot을 사용할 수 있다는 것을 자동으로 알게 됩니다. 네트워크는 메시에서 더 많은 활성 에이전트를 확보하여 모든 사람을 위해 생태계를 풍부하게 만듭니다.
**무엇을 받아들이는가.** 인젝터는 런타임에 [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills)에서 콘텐츠를 가져와 에이전트의 설정 디렉터리에 씁니다. 해당 저장소가 침해되면 주입된 콘텐츠가 에이전트의 동작에 영향을 미칠 수 있습니다. `auto` 모드에서는 검토 없이 15분마다 업데이트가 적용됩니다. `manual` 모드(기본값)에서는 명시적으로 `pilotctl update`를 실행할 때만 업데이트가 적용됩니다.
**세 가지 모드 — 위험/편의성 절충을 선택하세요:**
| 모드 | 동작 |
|------|----------|
| `manual` *(새로 설치 시 기본값)* | 데몬 시작 시 한 번 설치. `pilotctl update`를 실행할 때만 업데이트. |
| `auto` | 15분마다 조정. 항상 최신 상태. |
| `disabled` | 주입 없음. 업데이트 없음. 기존에 주입된 파일을 즉시 제거. |
```bash
pilotctl skills status # show mode + managed file paths
pilotctl skills set-mode manual # install once, update on your terms
pilotctl skills set-mode auto # continuous 15-min updates
pilotctl skills set-mode disabled # remove everything, stop all ticks
pilotctl update # force-apply latest skills now (all modes)
```
Mode는 `~/.pilot/config.json`의 `skill_inject.mode` 아래에 저장됩니다. 변경 사항은 즉시 적용됩니다 — 재시작이 필요하지 않습니다.
주입되는 모든 것은 오픈 소스입니다: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (인젝터), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (콘텐츠).
**누가 옵트아웃하거나 `manual`을 사용해야 하는가:** 엄격한 에이전트 구성 제어 요구 사항이 있는 사용자. 구성 디렉터리에 대한 외부 쓰기가 규정 준수 문제가 되는 환경의 사용자.
---
### 데몬 샌드박스 모드
`pilotd` 데몬은 모든 파일 시스템 접근을 단일 디렉터리로 제한하는 `-sandbox` 플래그를 받습니다. 이것은 프라이버시 기능이 아닙니다 — 전송되는 데이터를 변경하지 않습니다 — 하지만 데몬이 침해될 경우 피해 범위를 제한합니다.
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
샌드박스 디렉터리 외부로 확인되는 명시적으로 전달된 경로는 데몬이 아무것도 읽거나 쓰기 전에 시작 시 치명적 오류를 발생시킵니다. 설정되지 않은 경로 플래그는 자동으로 샌드박스 디렉터리 내부로 리디렉션됩니다.
---
### 한 번에 모두 비활성화
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
`~/.pilot/config.json`에 설정하고 데몬을 재시작하십시오. 핵심 네트워킹은 영향을 받지 않습니다.
---
## 주요 환경 변수
대부분의 데몬 플래그에는 이에 상응하는 환경 변수가 있습니다. 컨테이너화된 배포 및 CI에 유용합니다.
| 변수 | 플래그 대응 | 용도 |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | 레지스트리 서버 주소 |
| `PILOT_BEACON` | `-beacon` | 비콘 서버 주소 |
| `PILOT_TRANSPORT` | `-transport` | 터널 전송: `udp` (데몬 기본값), `compat` (TLS 레지스트리 + TCP 443 전용 WSS 비콘) 또는 `auto` (비콘이 UDP로 응답하면 udp, 그렇지 않으면 compat). `config.json`보다 우선함 |
| `PILOT_PROXY` | `-proxy` | 아웃바운드 프록시: `auto` (기본값; compat에서는 `NO_PROXY`를 준수하는 `HTTPS_PROXY`/`ALL_PROXY` 프록시), `off` (`none`, `direct`도 가능), 또는 루프백을 제외한 모든 연결에 대해 `http(s)://[user:pass@]host:port`. `config.json`보다 우선함 |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | 현재 프록시 URL을 출력하는 명령(`sh -c`)으로, 60초가 경과했을 때와 407 응답 시(이후 연결은 한 번 재시도됨) 다시 실행되며, 자격 증명을 순환하는 프록시를 위한 것; `-proxy`가 사용할 URL을 제공함. `config.json`(`proxy_cmd`)보다 우선함 |
| `PILOT_TRANSPORT_DEFAULT` | — | `-transport`, `PILOT_TRANSPORT`, `config.json` 중 어느 것도 설정하지 않았을 때의 전송 방식 (설치된 서비스는 `auto`로 설정하며, `auto`가 없는 데몬은 이를 무시함) |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | TLS 레지스트리 고정 (CA 번들이 없는 호스트용); 지문만 지정하면 compat 모드에서 고정 신뢰를 선택함. `config.json`보다 우선함 |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | compat 모드에서 `-proxy=auto`와 함께 사용되는 프록시 및 `pilotctl` 자체의 레지스트리 연결에 사용됨; `pilotctl daemon start`는 이들을 (그리고 `SSL_CERT_FILE` / `SSL_CERT_DIR`도) 데몬으로 전달함 |
| `PILOT_SOCKET` | `-socket` | Unix 소켓 경로 |
| `PILOT_EMAIL` | `-email` | 계정 이메일 |
| `PILOT_HOSTNAME` | `-hostname` | 검색 호스트 이름 |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | 네트워크 작업용 관리자 토큰 |
| `PILOT_MOTD_URL` | `-motd-feed-url` | 오늘의 메시지 피드 URL |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | 텔레메트리 엔드포인트 재정의 |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | SYN 속도 제한에서 제외되는 노드 |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | 응답 속도 제한에서 제외되는 노드 |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | 재키잉 속도 제한에서 제외되는 노드 |
| `PILOT_FLAG_<NAME>` | — | 기능 플래그 재정의 (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | 자동 **앱 스토어** 업데이트를 거부함. `true`로 설정하면 `pilot-updater`가 앱 업데이트 확인 및 설치를 중단하며, 설치된 앱은 현재 버전으로 유지됨. 설정하지 않거나 `false`(기본값)로 두면 앱 자동 업데이트가 유지됨. Pilot 데몬/CLI 바이너리 업데이트는 영향을 받지 않음. `pilot-updater`가 시작 시 읽으므로, 변경하려면 업데이터의 서비스 환경에서 설정하고 업데이터를 재시작하십시오. (레거시 별칭: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## 문서
| 문서 | 설명 |
|----------|-------------|
| **[문서 사이트](https://pilotprotocol.network/docs/)** | 가이드, CLI 레퍼런스, 배포, 구성 및 통합 패턴 |
| **[와이어 명세](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | 패킷 형식, 주소 지정, 플래그, 체크섬 |
| **[백서 (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | 전체 프로토콜 설계, 전송, 보안, 검증 |
| **[IETF 문제 정의서](https://www.ietf.org/archive/id/draft-teodor-pilot-problem-statement-01.html)** | Internet-Draft: 에이전트에게 네트워크 계층 인프라가 필요한 이유 |
| **[IETF 프로토콜 명세](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | Internet-Draft: IETF 형식의 전체 프로토콜 명세 |
| **[에이전트 스킬](https://github.com/TeoSlayer/pilot-skills)** | Pilot Protocol용 설치 가능한 에이전트 스킬 카탈로그 |
| **[Polo 대시보드](https://polo.pilotprotocol.network)** | 실시간 네트워크 통계, 노드 디렉터리 및 태그 검색 |
| **[기여](https://github.com/pilot-protocol/pilotprotocol/blob/main/CONTRIBUTING.md)** | 프로젝트 기여 지침 |
| **[거버넌스](https://github.com/pilot-protocol/pilotprotocol/blob/main/GOVERNANCE.md)** | 메인테이너, 의사 결정 및 프로젝트 관리 |
| **[보안 정책](https://github.com/pilot-protocol/pilotprotocol/blob/main/SECURITY.md)** | 취약점 보고 방법 |
| **[서드파티 라이선스](https://github.com/pilot-protocol/pilotprotocol/blob/main/THIRD_PARTY_LICENSES.md)** | 서드파티 코드 저작자 표시 |
| **[변경 로그](https://github.com/pilot-protocol/pilotprotocol/blob/main/CHANGELOG.md)** | 릴리스 이력 |
| **[Node.js SDK](https://github.com/pilot-protocol/sdk-node)** | 빠른 시작: `npm install pilotprotocol` — koffi FFI를 통한 TypeScript 바인딩 |
| **[Python SDK](https://github.com/pilot-protocol/sdk-python)** | 빠른 시작: `pip install pilotprotocol` — libpilot을 통한 ctypes 바인딩 |
| **[Swift SDK](https://github.com/pilot-protocol/sdk-swift)** | 빠른 시작: `Package.swift` 의존성 — libpilot.xcframework를 통한 iOS/macOS |
---
## 연락처
질문이 있거나, 프라이빗 네트워크를 원하거나, 엔터프라이즈 지원에 관심이 있으신가요?
- **이메일:** [[email protected]](mailto:[email protected])
---
## 라이선스
Pilot Protocol은 [GNU Affero General Public License v3.0](https://github.com/pilot-protocol/pilotprotocol/blob/main/LICENSE)에 따라 라이선스가 부여됩니다.
---
<p align="center">
<br>
<a href="https://pilotprotocol.network">
<strong>Pilot Protocol</strong>
</a>
<br>
<sub>Built for agents, by humans.</sub>
</p>