APX의 로컬 데몬(Local Daemon)에 Bearer Token을 적용한 이유

APX를 구축하면서 동일한 문제에 계속 직면했습니다. 데몬(daemon)을 추가하는 순간, 공유된 제어 표면(shared control surface)이 생성된다는 점입니다. CLI, 웹 관리자(web admin), Telegram 훅(hooks), 향후 도구들, 그리고 디버깅 도우미들까지 모두 동일한 로컬 API와 통신하게 됩니다. 이는 유용하지만, 동시에 위험 요소가 됩니다.

저의 첫 번째 본능은 평소와 같았습니다. "localhost에서 실행되니까 괜찮아."라는 생각이었죠. 이 문장은 안전하게 들리지만, 너무 느슨합니다. Localhost는 신뢰 경계(trust boundary)가 아닙니다. 그것은 단지 네트워크 주소일 뿐입니다. 만약 동일한 OS 사용자 권한 아래에 있는 다른 프로세스가 데몬에 접근할 수 있다면, "로컬(local)"이 "무해함(harmless)"을 의미하지는 않습니다.

그것이 바로 APX가 이제 데몬 API에 Bearer Token을 요구하는 이유입니다.

구현은 작지만, 설계 선택은 중요합니다. APX는 시작 시 0600 권한으로 ~/.apx/daemon.token에 새로운 토큰을 작성합니다. CLI는 이를 자동으로 읽기 때문에 일반적인 사용 환경은 평소와 다름없이 유지됩니다. 인증되지 않은 유일한 엔드포인트(endpoint)는 GET /health이며, CLI는 토큰 파일을 읽기 전에 데몬이 살아있는지 확인하는 용도로 이를 사용할 수 있습니다.

이를 통해 제가 실제로 원했던 보안 속성을 얻었습니다. 데몬은 여전히 사용하기 쉬우면서도, 더 이상 개방된 로컬 제어 소켓(local control socket)이 아닙니다.

이것을 수행할 가치가 있었던 이유

APX는 단순한 장난감 프로세스가 아닙니다. 프로젝트, 에이전트(agents), 세션(sessions), 메시지 로그, 루틴(routines), 그리고 런타임 상태(runtime state)를 관리합니다. 또한 연결된 런타임(runtimes)과 플러그인(plugins)을 통해 작업을 실행할 수도 있습니다. 도구가 이 정도로 많은 일을 수행하게 되면, 취약한 경계(weak boundary)로 인한 비용은 빠르게 증가합니다.

여기서의 위협 모델(threat model)은 인터넷상의 원격 공격자가 아닙니다. 그것은 더 일상적이고 현실적인 것입니다. 즉, 침해된 npm 의존성(dependency), 길을 잃은 스크립트, 악성 도우미, 또는 동일한 사용자로 실행되는 기타 프로세스입니다. 만약 해당 프로세스가 데몬 API를 호출할 수 있다면, 단순히 상태 페이지를 읽는 것 이상의 일을 할 수 있습니다. 작업을 트리거하고, 메모리를 조사하며, 프로젝트 상태와 상호작용할 수 있습니다.

이는 이론적인 우려가 아닙니다. 로컬 개발 도구들이 "같은 머신"이 "같은 신뢰"를 의미한다고 가정할 때 저지르는 전형적인 실수입니다.

실제 적용 시 무엇이 바뀌었나

이 토큰 덕분에 API를 노출하지 않으면서도 APX 워크플로우를 단순하게 유지할 수 있었습니다.

개발자 경험(Developer Experience)은 여전히 기본적으로 단일 명령 경로를 따릅니다:

apx init
apx run sofia --runtime claude-code "Review the open PRs and summarize them"
apx messages tail

CLI가 토큰을 자동으로 처리하므로, 일반적인 사용 중에 인증(Auth)에 대해 고민할 필요가 없습니다. 이것이 중요한 부분입니다. 기억해야 하는 보안 제어는 결국 소홀해지기 마련입니다. 일반적인 경로에서 보이지 않는 보안 제어가 살아남는 경향이 있습니다.

또한 데몬(Daemon)은 사용자 관점에서 여전히 로컬 런타임(Local Runtime)이라는 동일한 성격을 유지합니다. 저는 로그인 장벽, 원격 계정 모델, 또는 클라우드 의존성을 원하지 않았습니다. 제가 원했던 것은 머신 로컬(Machine-local) 워크플로우를 온전히 유지하면서도 공유 API를 보호할 수 있는 최소한의 검증이었습니다.

localhost만으로는 충분하지 않았던 이유

이 부분은 많은 로컬 도구들이 잘못 알고 있다고 생각하는 지점입니다.

로컬 API는 브라우저가 외부 세계에서 볼 수 없기 때문에 프라이빗(Private)하게 느껴집니다. 하지만 APX는 단순한 브라우저 앱이 아닙니다. 메모리를 읽고, 메시지를 테일링(Tail)하며, 작업을 시작하고, 여러 인터페이스(Surfaces)에 걸쳐 동작을 라우팅할 수 있는 명령어를 가진 데몬입니다. 즉, 진짜 질문은 "인터넷이 여기에 접근할 수 있는가?"가 아닙니다. 진짜 질문은 "이 머신 위의 다른 어떤 코드가 여기에 접근할 수 있는가?"입니다.

이 질문을 던지는 순간, 답이 달라집니다.

Bearer Token이 모든 문제를 해결해주지는 않습니다. 사용자가 허용된 동작을 하는 것을 막지는 못하며, 데몬을 무적으로 만들지도 않습니다. 하지만 보안 수준을 "포트를 추측할 수 있는 모든 프로세스"에서 "토큰 파일을 읽을 수 있는 프로세스"로 높여줍니다.

이것은 의미 있는 개선입니다.

내가 수용한 트레이드오프(Tradeoff)

모든 보안 경계는 어딘가에 마찰(Friction)을 발생시킵니다. 잘못된 방식의 인증은 로컬 도구를 무겁게 만듭니다. 즉각적이어야 할 작업에 자격 증명을 입력하게 만들기 때문입니다.

저는 그것을 원하지 않았습니다.

따라서 토큰은 자동적이어야 하고, 데몬(daemon) 시작 시마다 수명이 짧아야 하며, 일반적인 CLI 사용 시에는 보이지 않아야 했습니다. 그래야 보안 비용을 낮게 유지할 수 있습니다. 데몬은 여전히 로컬에서 시작되고, CLI는 여전히 즉각적인 느낌을 주며, 브라우저 관리자(browser admin)는 여전히 동일한 로컬 백엔드(local backend)와 통신합니다. 경계는 존재하지만, 그것이 제품의 핵심 요소가 되지는 않습니다.

이것이 제가 APX에서 계속 선호하는 패턴입니다. 제어 평면(control plane)을 로컬에 유지하고, 상태(state)를 로컬에 유지하며, 설계를 정직하게 만드는 최소한의 보호 장치만을 추가하는 것입니다.

더 큰 교훈

APX를 구축하면서 저는 다양한 형태로 같은 교훈을 계속 얻고 있습니다. 어려운 점은 도구를 강력하게 만드는 것이 아닙니다. 어려운 점은 그 강력함을 읽기 쉽게(legible) 만드는 것입니다.

인증(auth)이 없는 데몬을 만드는 것은 쉽습니다. 인증이 있으면서도 여전히 로컬처럼 느껴지는 데몬을 만드는 데는 더 많은 주의가 필요합니다. 하지만 그 추가적인 주의는 아키텍처(architecture)를 일관되게 만들기 때문에 보상을 받습니다. APC는 휴대 가능한 프로젝트 컨텍스트(portable project context)에 집중할 수 있습니다. APX는 실행(execution)에 집중할 수 있습니다. 그리고 그 사이의 가교는 막연한 바람이 아닌 실제적인 경계를 가질 수 있습니다.

이것이 제가 APX 데몬에 Bearer Token을 적용한 이유입니다.

이것은 작은 변화입니다. 또한 시스템의 나머지 부분을 온전하게 유지하는 종류의 작은 변화이기도 합니다.

소스 컨텍스트(source context)를 확인하고 싶다면, APX 리포지토리(repo)와 보안 노트(security notes)부터 시작하세요:

• https://github.com/agentprojectcontext/apx
• https://github.com/agentprojectcontext/apx/blob/main/SECURITY.md