ghostwright/specter

당신의 신뢰를 얻는 AI 에이전트.

AI 에이전트는 서버가 필요합니다. 임시적인 샌드박스나 사라지는 컨테이너, 공유 런타임 환경이 아닙니다. 자체 IP 주소, 자체 TLS 인증서, 자체 systemd 프로세스를 가진 실제 VM이 필요합니다. Specter는 이를 90초 만에 제공합니다.

specter deploy scout --role swe --env ANTHROPIC_API_KEY=sk-ant-... 
# scout.yourdomain.com은 HTTPS, 상태 모니터링 및 자동 재시작 기능이 활성화된 상태로 작동합니다

단 하나의 명령으로 Hetzner Cloud의 전용 VM, Cloudflare를 통한 자동 DNS 설정, Let's Encrypt를 이용한 TLS, systemd 강화(hardening), 방화벽, 그리고 상태 확인 엔드포인트를 확보할 수 있습니다. 인프라의 소유권도, 데이터의 소유권도 모두 사용자에게 있습니다. 벤더 종속성(vendor lock-in)이 없습니다.

전체 데모 시청하기: 두 개의 에이전트를 배포하고, SSH로 접속하여 로그를 확인하는 모든 과정이 TUI에서 가능합니다.

AI 에이전트는 일시적인 컨테이너가 아닌 지속적인 인프라가 필요합니다. 며칠 동안 실행되고, 상태(state)를 유지하며, 웹훅을 수신하고, 재시작에도 살아남아야 합니다. Specter는 모든 것이 사전 구성된 프로덕션급 VM을 각 에이전트에게 제공합니다.

빠름(Fast) -- 골든 스냅샷으로부터 90초 만에 배포됩니다. 배포 시 Docker 빌드나 패키지 설치가 필요 없습니다.보안(Secure) -- 비밀 정보는 cloud-init을 통해 주입되고 부팅 후 삭제됩니다. systemd 강화 및 이중 방화벽을 적용합니다.관찰 가능함(Observable) -- 상태 확인 엔드포인트, systemd 저널(journals), 실시간 상태 점검이 가능하며 필요할 때 SSH로 접속할 수 있습니다.에이전트 네이티브(Agent-native) -- 모든 명령어는 --json 출력을 지원하고 비대화형 사용을 위해 --yes를 지원합니다. AI 간의 오케스트레이션(orchestration)을 위해 구축되었습니다.저렴함(Cheap) -- Hetzner VM은 월 $3.49부터 시작합니다. 추가 마크업이나 플랫폼 수수료가 없습니다.사용자 소유(Yours) -- Apache 2.0 라이선스입니다. 포크하여, 확장하여, 원하는 조건에서 실행할 수 있습니다.

시작하기 전에 세 가지가 필요합니다:

1. Hetzner Cloud 계정 -- console.hetzner.cloud. 프로젝트를 생성한 후, Security > API Tokens에서 읽기 및 쓰기 권한을 가진 API 토큰을 생성하세요.

2. 도메인이 있는 Cloudflare 계정 -- dash.cloudflare.com. 도메인 개요 사이드바에서 Zone ID를 가져오세요. Edit zone DNS 권한이 있는 API 토큰을 생성하세요.

3. Hetzner의 SSH 키 — Hetzner 콘솔 > Security > SSH Keys에서 공개 키를 업로드하세요. 필요하다면: ssh-keygen -t ed25519

이것만 있으면 됩니다. 이 것들만 갖추면 나머지는 모두 자동화됩니다.

Homebrew (권장):

brew install ghostwright/specter/specter

셸 스크립트:

curl -sSL https://raw.githubusercontent.com/ghostwright/specter/main/scripts/install.sh | sh

소스에서 설치 (개발용):

git clone https://github.com/ghostwright/specter.git
cd specter && make build
./bin/specter version

# 1. 설정 (토큰 유효성 검사, 방화벽 생성, 서버 유형 캐싱)
specter init
# 2. 골든 스냅샷 빌드 (최초 1회만, 약 5분 소요)
...

대시보드는 키보드 단축키를 사용하여 배포, SSH 접속, 로그 보기 및 에이전트 관리를 할 수 있게 해줍니다. d를 눌러 첫 번째 에이전트를 배포하고, s를 눌러 SSH로 접속하며, l을 누르면 로그가 표시됩니다. 기억할 플래그가 없습니다.

또는 자동화를 위해 CLI를 직접 사용할 수 있습니다:

specter deploy scout --role swe --env ANTHROPIC_API_KEY=sk-ant-... 
curl https://scout.yourdomain.com/health

모든 명령어는 구조화된 출력을 위해 --json과 프롬프트 건너뛰기를 위한 --yes / -y를 지원합니다.

specter deploy <name> [플래그]
--role string 에이전트 역할 (기본값 "swe")
--server-type string Hetzner 서버 유형 (설정 파일에서 기본값)
...

에이전트의 .env 파일에 비밀 정보와 설정을 주입합니다:

# 개별 변수
specter deploy scout --role swe \
--env ANTHROPIC_API_KEY=sk-ant-... \
...

가격은 specter init 중에 Hetzner API에서 동적으로 가져옵니다. 일반적인 x86 유형은 다음과 같습니다:

서버 이름을 잘못 입력하면 Specter가 가장 가까운 일치 항목을 제안합니다:

$ specter deploy test --server-type potato
unknown server type 'potato'. Did you mean 'cpx11'?

Claude에게 이 리포지토리를 주면 인프라를 배포하고 관리할 수 있습니다. CLAUDE.md 파일이 완전한 컨텍스트를 자동으로 제공합니다.

예시 프롬프트:

뉘른베르크의 cx33에서 소프트웨어 엔지니어링(swe)을 위한 'scout'이라는 새 에이전트를 배포하세요. 제 .env 파일에 있는 API 키를 사용하세요.

Claude가 실행할 내용:

specter deploy scout --role swe --json --yes \
--env-file .env --server-type cx33 --location nbg1

예시 프롬프트:

실행 중인 모든 에이전트와 그들의 상태를 보여주세요.

specter list --json
specter status scout --json

예시 프롬프트:

scout에 SSH로 접속하여 로그를 확인하세요.

specter ssh scout
# 또는 외부에서:
specter logs scout -n 50

모든 명령어는 구조화된 출력을 위한 --json과 프롬프트를 건너뛰기 위한 --yes를 지원합니다. 이를 통해 Specter는 AI 에이전트, CI/CD 파이프라인 또는 스크립트에 의해 완전히 프로그래밍 가능해집니다.

specter deploy scout --role swe --json --yes \
--env ANTHROPIC_API_KEY=sk-ant-...

{
"status": "deployed",
"name": "scout",
...

specter status scout --json # 상태, 가동 시간, 서버 정보
specter list --json # 모든 에이전트를 JSON 배열로
specter destroy scout --json --yes

여러분의 머신 Hetzner Cloud
+------------------+ +------------------------------+
| specter CLI | | VM (Ubuntu 24.04) |
...

각 에이전트 VM에는 다음 내용이 포함됩니다:

**골든 스냅샷(golden snapshot)**에서 가져온 Ubuntu 24.04
사이드카 컨테이너를 위한 Docker 29.x
JavaScript 런타임으로 사용되는 Bun 1.3.x
Let's Encrypt를 통한 자동 TLS를 위한 Caddy 2.11.x
보안 강화(NoNewPrivileges, ProtectSystem, PrivateTmp, MemoryMax)가 적용된 systemd
Hetzner Cloud 방화벽 + ufw(포트 22, 80, 443만 허용)
SSH 무차별 대입 공격 보호를 위한 fail2ban
메모리 집약적 워크로드를 위한 2 GB 스왑(swap)

현재 최소한의 상태 엔드포인트만 배포합니다. 전체 specter-agent 런타임은 개발 중입니다.

스냅샷은 부팅 시간을 최소화하기 위해 가장 작은 x86 서버(cx23, 40 GB 디스크)를 기반으로 구축됩니다. Hetzner는 스냅샷 복원 시 전체 디스크 할당을 복사하므로, 디스크가 작을수록 배포 속도가 빠릅니다. cx23 기반의 모든 스냅샷은 더 큰 x86 유형에서 작동합니다.

토큰 마스킹(Token redaction) -- API 토큰은 JSON 출력이나 오류 메시지에 포함되지 않습니다.
파일 권한(File permissions) -- ~/.specter/config.yaml에서 설정하며, 0600으로 저장됩니다.
비밀 정리(Secret cleanup) -- Cloud-init 사용자 데이터(환경 변수 포함)는 부팅 후 삭제됩니다.
systemd 강화(systemd hardening) -- NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only, PrivateTmp, MemoryMax=2G, TasksMax=256이 적용됩니다.
듀얼 방화벽(Dual firewall) -- Hetzner Cloud Firewall와 ufw를 사용하며, 22/80/443 포트만 허용합니다.
SSH -- StrictHostKeyChecking=no를 사용합니다 (임시 VM의 알려진 트레이드오프).

비용은 얼마인가요?

인프라 비용은 서버 유형에 따라 에이전트당 월 $3~$19입니다. 가격은 Hetzner API에서 가져오며 변경될 수 있습니다. 에이전트 API 비용(Anthropic, OpenAI 등)은 별도입니다.

제 도메인을 사용할 수 있나요?

예. specter init 시 도메인을 지정하면 됩니다. Cloudflare 관리 DNS 영역이 필요합니다.

Hetzner가 다운되면 어떻게 되나요?

Specter는 에이전트 상태를 로컬에 저장합니다. 배포 중 API에 연결할 수 없으면 깨끗하게 실패합니다. 에이전트를 실행하는 동안에는 VM만 작동하면 계속 작동합니다.

보안성이 높은가요?

비밀은 HTTPS를 통해 cloud-init으로 주입되며 부팅 후 정리됩니다. VM은 세 개의 포트로 방화벽 처리됩니다. systemd는 강화된 지침으로 에이전트를 실행합니다. 보안(Security) 섹션을 참조하세요.

VM에 SSH로 접속할 수 있나요?

예. specter ssh <name>을 사용하면 specter 사용자로 연결됩니다. 관리자 액세스를 위해서는 --root를 사용하세요.

에이전트 코어는 어떤가요?

현재 최소한의 상태 확인 엔드포인트(v0.1.0 플레이스홀더)만 배포합니다. 도구 사용, 작업 큐, MCP 통합 기능이 포함된 전체 specter-agent 런타임은 개발 중입니다.

git clone https://github.com/ghostwright/specter.git
cd specter && make build
# 실제 인프라에 테스트하기
... 

서버 유형별 테스트, 개선된 에이전트 런타임, 그리고 문서화가 필요합니다. 실제 인프라가 필요한 AI 에이전트를 구축하고 있다면 이 프로젝트가 적합합니다.

만약 LLM으로서 이 레포지토리를 처음 읽는다면, 알아야 할 것들이 있습니다.

Specter의 기능: 전용 Hetzner Cloud VM에 자동 DNS(Cloudflare) 및 TLS(Caddy를 통한 Let's Encrypt)를 프로비저닝합니다. 각 VM은 자체 서브도메인, 상태 엔드포인트, systemd 프로세스 관리 기능을 갖춘 독립적인 에이전트 서버로 실행됩니다. CLI는 전체 수명 주기(생성, 모니터링, 업데이트, 파괴)를 처리합니다.

프로그래밍 방식으로 사용하는 방법: 항상 --json 및 --yes 플래그를 전달하세요. 대화형 모드를 사용하지 마세요.

# 배포
specter deploy <name> --role swe --json --yes --env KEY=VALUE
# 상태 확인
...

알아두면 좋은 핵심 사항:

• VM 부팅에는 70~90초가 걸립니다. 120초 이전에 타임아웃되지 않도록 하세요.
• TLS 프로비저닝은 서비스 시작 후 5~8초가 소요됩니다.
• 배포 전에 골든 스냅샷이 존재해야 합니다. 먼저 specter image build를 실행하세요. - x86 전용입니다. ARM 서버는 지원하지 않습니다.
• 위치: nbg1(뉘른베르크), fsn1(팔켄슈타인), hel1(헬싱키). 모두 EU 지역입니다. - Cloudflare에서 DNS 레코드가 proxied: false여야 TLS 오류가 발생하지 않습니다. - 상태 엔드포인트는 항상 https://<name>.<domain>/health에 있으며 JSON을 반환합니다.

더 깊은 맥락: 리포지토리 루트의 CLAUDE.md를 읽어보세요. 여기에는 전체 프로젝트 구조, 고정 파일 목록 및 아키텍처 세부 정보가 포함되어 있습니다.

Apache 2.0. LICENSE 참조.