Pilot Protocol은 데이터 경로에서 플랫폼을 제외합니다. 가벼운 **rendezvous** 서비스가 검색 및 NAT traversal을 처리하지만, 에이전트들이 서로를 찾으면 인증되고 암호화된 터널을 통해 직접 통신합니다:```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

신뢰할 수 있는 피어가 확보되면 에이전트 간 메시징은 포트 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>

Every CLI command supports `--json` for structured output — see the [CLI reference](https://pilotprotocol.network/docs/cli-reference) for the full surface area.

<details>
<summary><strong>Example JSON output</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\""}

각 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 ID 키
- 기본적으로 노드는 비공개입니다.
- 상호 신뢰 핸드셰이크 프로토콜 (서명됨, 레지스트리를 통한 릴레이)

**운영**
- 핵심 프로토콜: 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

또한 핑(ping) 및 벤치마크(benchmark)를 할 수 있습니다:```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha

설치 중에 호스트 이름과 이메일을 설정하세요:```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh

앱은 (ed25519)로 서명되며, 설치 시와 매 실행 시 확인됩니다. 데몬은 모든 앱 간 호출을 중개합니다 — 앱은 매니페스트에 선언된 메서드를 통해서만 접근할 수 있습니다. 앱 빌드, 서명, 게시에 대한 내용은 [App Store 문서](https://pilotprotocol.network/docs/app-store)를 참조하세요.

---

## 테스트```bash
go test -parallel 4 -count=1 ./tests/

`~/.pilot/config.json`에 설정합니다. 텔레메트리 클라이언트는 완전한 no-op이 됩니다 — 다이얼도, 고루틴도 없습니다. CLI 명령어에 즉시 적용됩니다.

**옵트아웃 대상:** 엄격한 텔레메트리 금지 정책, 고감도 배포 환경, 또는 아웃바운드 텔레메트리가 바람직하지 않은 자동화 파이프라인이 있는 사용자.

---

### 브로드캐스트 — 위험: 중간

**기능.** 네트워크 관리자가 인증된 단일 데이터그램을 네트워크 내 모든 에이전트에게 동시에 전송할 수 있습니다. 데몬이 관리자 토큰을 확인하고 페이로드를 에이전트로 전달합니다.

**도움을 받는 대상.** 플릿 운영자가 모든 에이전트를 단일 명령으로 조정합니다 — 구성 새로고침, 롤링 재시작, 사고 대응 — O(N)개의 개별 메시지 없이. 대규모 피어 메시에서 유일한 O(1) 조정 메커니즘입니다.

**수용하는 사항.** 네트워크의 관리자 토큰을 보유한 모든 당사자가 에이전트에 임의의 데이터를 전달할 수 있습니다. 토큰의 보안이 경계입니다: 토큰이 유출되거나 신뢰하지 않는 사람이 보유할 경우, 공격자가 에이전트에 접근할 수 있습니다.

**옵트아웃 방법:**```json
{"consent": {"broadcasts": false}}

**옵트아웃하려면:**```json
{"consent": {"reviews": false}}

모드는 `~/.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

`~/.pilot/config.json`에 설정하고 데몬을 재시작하세요. 핵심 네트워킹에는 영향을 미치지 않습니다.

---

## 주요 환경 변수

대부분의 데몬 플래그에는 동등한 환경 변수가 있습니다. 컨테이너화된 배포와 CI에 유용합니다.

| 변수 | 플래그 대응 | 용도 |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | 레지스트리 서버 주소 |
| `PILOT_BEACON` | `-beacon` | 비콘 서버 주소 |
| `PILOT_SOCKET` | `-socket` | 유닉스 소켓 경로 |
| `PILOT_EMAIL` | `-email` | 계정 이메일 |
| `PILOT_HOSTNAME` | `-hostname` | 발견(Discovery) 호스트명 |
| `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)** | 인터넷 초안: 에이전트가 네트워크 계층 인프라가 필요한 이유 |
| **[IETF 프로토콜 명세](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | 인터넷 초안: IETF 형식의 전체 프로토콜 명세 |
| **[에이전트 스킬](https://github.com/TeoSlayer/pilot-skills)** | Pilot Protocol용 설치 가능한 에이전트 스킬 카탈로그 |
| **[Polo 대시보드](https://polo.pilotprotocol.network)** | 실시간 네트워크 통계, 노드 디렉터리 및 태그 검색 |
| **[기여하기](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/CONTRIBUTING.md)** | 프로젝트에 기여하기 위한 지침 |
| **[거버넌스](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/GOVERNANCE.md)** | 관리자, 의사 결정 및 프로젝트 관리 |
| **[보안 정책](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/SECURITY.md)** | 취약점 신고 방법 |
| **[타사 라이선스](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/THIRD_PARTY_LICENSES.md)** | 타사 코드에 대한 저작자 표시 |
| **[변경 로그](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/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/HEAD/LICENSE)에 따라 라이선스가 부여됩니다.

---

<p align="center">
  <br>
  <a href="https://pilotprotocol.network">
    <strong>Pilot Protocol</strong>
  </a>
  <br>
  <sub>인간이 에이전트를 위해 만들었습니다.</sub>
</p>