몇 주 전, 저는 제가 실험용으로 사용해 온 코딩 에이전트 하네스(agent harness)인 Pi에 대해 사내 강연을 한 번 더 진행했습니다. 만약 Claude Code 포스트가 매우 완성도 높은 도구를 최대한 활용하는 법에 관한 것이었다면, 이번 포스트는 그 반대에 가깝습니다. 가능한 가장 작은 도구이며, 아무것도 숨기지 않기 때문에 정확히 그 점 덕분에 배울 수 있는 모든 것을 담고 있습니다.

주의 사항: 이것은 실험적인 영역이며, 여러분의 일상적인 워크플로우(workflow)에 대한 권장 사항이 아닙니다. Pi는 강력한 만큼 위험하기도 합니다. 이 포스트의 재미있는 점 중 하나는 여러분이 스스로 발등을 찍는 일 없이 이것을 가지고 놀 수 있도록 템플릿을 제공하는 것입니다.

Pi란 무엇인가

Pi는 실제로 OpenClaw의 핵심에 위치한 에이전트 하네스(agent harness)입니다. 극도로 미니멀합니다. 네 가지 도구 — read, write, bash, ls — 만을 가지고 있으며, 이것만으로 모델은 컴퓨터에서 무엇이든 할 수 있습니다. 플랜 모드(plan mode), MCP(Model Context Protocol), 서브 에이전트(sub-agents), Jira 연동, 또는 GitHub 리포지토리(repo)와의 연결도 없습니다. 무엇보다도 권한 시스템(permissions system)과 가드레일(guardrails)이 없습니다. 여러분이 무언가를 요청하면 모델은 그것을 수행하기 위해 필요한 모든 것, 즉 글로벌 의존성(global dependencies) 설치나 bash 스크립트 작성을 포함하여 필요한 작업을 수행합니다.

제가 가장 좋아하는 비유는 다음과 같습니다: Pi는 에이전트 하네스(agent harnesses)에게 IDE가 vim에게 갖는 관계와 같습니다. 이것은 최소한의 요소이며, 그 위에 원하는 것은 무엇이든 추가할 수 있습니다. vim 위에 자신만의 IDE를 구축할 수 있는 것처럼, Pi 위에 자신만의 Claude Code를 구축할 수 있습니다.

미니멀하지만, 주관적인 특성이 없는 것은 아닙니다. Pi를 흥미롭게 만드는 세 가지 매우 구체적인 특징이 있습니다:

1. 투명성 (Transparency). 모델의 전체 사고 과정, 모든 도구 호출(tool call), 모든 명령 및 그 출력 결과가 세션 출력에 그대로 나타납니다.
2. 세션 내보내기 (Session export). 공유할 수 있는 전체 세션이 포함된 HTML 파일을 생성합니다.
3. 트리 탐색 (Tree navigation). 어느 지점으로든 점프할 수 있고, 그 지점에서 세션을 재개하거나 세션 트리(session tree)에서 새로운 브랜치(branch)를 열 수 있습니다.

왜 투명성이 그토록 중요한가

이 점이 저를 정말로 사로잡았습니다. Claude Code를 사용하며 서브 에이전트(sub-agents)를 생성할 때, 여러분이 보는 것이라고는 "작업 중...(working…)"이라는 메시지와 그 결과뿐입니다. 새로운 버전들에서는 서브 에이전트의 세션으로 들어갈 수 있지만, 에이전트가 작업을 마치면 그 모든 것이 사라집니다. 하지만 Pi를 사용하면 모델이 매 단계에서 정확히 무엇을 하고 있는지 볼 수 있습니다. 서브 에이전트가 필요하다면, pi를 사용하여 pi 내부에서, tmux에서, 또는 백그라운드 프로세스로 생성하도록 요청할 수 있으며, 해당 세션들을 저장할 수도 있습니다.

HTML 내보내기(export) 기능을 통해 작은 UI로 모든 내용을 검토할 수 있습니다. 탐색 기능이 있는 사이드바를 통해 사용자 프롬프트(user prompts)만 필터링하거나, 도구 호출(tool calls)을 포함하거나 제외하고 모든 내용을 확인하거나, 어느 지점으로든 바로 이동할 수 있습니다. (이와 대조적으로 Claude의 내보내기 결과는 가공되지 않은 콘솔 텍스트뿐입니다.)

이것이 실무에서 어디에 유용할까요? 특정 프롬프트가 주어졌을 때 모델이 어떻게 행동하는지 학습하는 것입니다. 모델이 무언가를 틀리는지 또는 여러 번 시도하는지, 읽지 말아야 할 파일을 "읽기" 시작하는지, 혹은 프롬프트를 오해하는지(전체 "사고(thinking)" 출력도 함께 볼 수 있습니다) 등을 확인할 수 있습니다.

저는 대시보드의 일부 백분율을 막대 그래프로 교체하는 동일한 작업을 Opus를 사용하는 Claude와 오픈 소스 모델을 사용하는 Pi로 실행해 보았습니다. 두 세션을 나란히 비교하는 것이 전체 실험에서 가장 교육적인 부분이었습니다. 모델이 어디에서 예시를 필요로 하는지, 어디에서 테스트 작성을 잊어버리는지(참고로 둘 다 잊어버렸습니다)를 알 수 있었습니다.

안전하게 실행하기

Pi는 기본적으로 YOLO 모드로 실행됩니다. 권한 요청도, 질문도 없이 모델이 필요하다고 생각하는 작업을 수행합니다. 이를 사용자의 기기에 전역(globally)으로 설치하는 것은 매우 위험하며 전혀 권장되지 않습니다. 단 하나의 잘못된 프롬프트나 하나의 환각(hallucination)만으로도, 에이전트가 사용자의 자격 증명(credentials)과 전체 파일 시스템에 접근 가능한 상태로 bash를 실행하게 될 수 있기 때문입니다.

한 가지 해결책은 이를 Docker 컨테이너 안에 넣는 것입니다. 에이전트에게 세상의 전부란 프로젝트 폴더만 들어 있는 빈 컨테이너일 뿐입니다. 에이전트는 사용자의 환경 변수(사용자가 전달한 것만 포함)를 볼 수 없고, 시스템을 볼 수 없으며, 명시적으로 허용하지 않는 한 네트워크에도 접근할 수 없습니다. 이로 인해 파괴적인 행동을 할 위험이 대폭 감소합니다.

다음 Dockerfile을 템플릿으로 사용할 수 있습니다. 이 파일은 pi를 전역(globally)으로 설치하고, LiteLLM 또는 ollama를 사용하는 경우 프로바이더 확장(provider extension)을 복사하며, 권한이 없는 사용자(unprivileged user)로 실행될 수 있도록 모든 준비를 마칩니다.

FROM node:24-bookworm-slim

# 기본 도구 + pi 전역 설치
...

docker build -t pi-agent . 명령어로 빌드한 후, 이미지가 생성되면 다음과 같이 대화형(interactively)으로 실행하세요:

docker run -it \
  --cap-drop ALL \
  --security-opt no-new-privileges \
...

• --cap-drop ALL은 모든 Linux 기능(capabilities)을 제거하며, --security-opt no-new-privileges는 컨테이너 내부에서의 권한 상승(privilege escalation)을 방지합니다.
• Dockerfile에서 에이전트는 node 사용자(UID 1000, root 아님)로 실행되므로, sudo 권한이 없으며 에이전트가 생성한 파일은 사용자 1000의 권한을 가집니다. 이는 보통 시스템의 첫 번째 사용자이므로 사용자의 권한과 일치할 가능성이 높습니다.
• -v "$(pwd):/workspace"는 현재 디렉토리만 마운트(mount)합니다. 즉, 에이전트가 읽고, 수정하거나 실행할 수 있는 유일한 대상입니다.
• -e 옵션으로 전달한 환경 변수만 에이전트에 도달하며, 보통 API 키 외에는 아무것도 전달되지 않습니다.

언급할 만한 세부 사항이 하나 있습니다. 저는 이미지 안에 AGENTS.md를 넣어 에이전트에게 자신이 격리된 샌드박스(sandbox) 안에 있다는 사실을 알려줍니다. 에이전트가 보는 환경(DNS, 설치된 도구, 네트워크 등)은 실제 머신과 일치하지 않으므로 환경을 조사하려고 시도해서는 안 되며, 대신 사용자가 직접 확인할 수 있도록 지침을 제공해야 한다고 명시했습니다. 이 설정이 없으면 작은 모델들은 컨테이너 내부에서 dig나 whois를 실행하기 시작하며 스스로 혼란에 빠지게 됩니다.

별칭(alias)을 설정하면 단 두 번의 키 입력만으로 실행할 수 있습니다:

alias pi='docker run -it --cap-drop ALL --security-opt no-new-privileges -e API_KEY=$YOUR_API_KEY -v "$(pwd):/workspace" pi-agent'

pi라고 입력하는 것만큼 쉽습니다.

모델: 클라우드 프록시에서 오픈 소스까지

Pi는 모든 OpenAI 호환 제공업체(provider)와 통신할 수 있으며, 확장을 통해 몇 줄의 코드만 추가하면 새로운 제공업체를 추가할 수 있습니다. 구조는 다음과 같습니다 (제공업체의 baseUrl, 키, 모델 목록을 등록합니다):

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
...

LiteLLM과 같은 프록시를 사용하면 최첨단 모델(Frontier models, Claude 및 그 친구들)과 오픈 웨이트(open-weight) 모델을 모두 사용할 수 있으며, 바로 이 부분이 재미있는 지점입니다. 제가 테스트해 본 결과, GLM 5가 단연 최고였습니다 — Sonnet 수준 정도라고 말할 수 있으며, 이를 통해 많은 것을 할 수 있습니다. Minimax 2.5와 Kimi K2.5 또한 성능이 준수합니다. 모든 작업에 이 모델들을 사용하지는 않겠지만(MCP, 통합, 메모리, 하위 에이전트(sub-agents) 등이 부족하기 때문입니다...), 전체 세션을 지켜보며 몇 번 실행해 보는 것만으로도 오늘날 오픈 모델들이 어느 위치에 와 있는지에 대해 많은 것을 배울 수 있습니다.

Ollama를 이용한 로컬 모델

[

또 다른 옵션은 아무것도 외부로 전송하지 않고 자신의 기기에서 직접 모델을 실행하는 것입니다. Pi는 다른 모든 OpenAI 호환 제공업체와 마찬가지로 Ollama에 연결할 수 있습니다 (http://127.0.0.1:11434/v1를 가리킵니다).

에이전트 작업(agentic tasks)을 위해 Ollama 모델을 사용하는 것은 완전히 플러그 앤 플레이(plug-and-play) 방식은 아닙니다. Modelfile을 사용하여 적절한 설정이 포함된 변형 모델을 만들어야 합니다. 핵심은 온도(temperature)를 낮추고 컨텍스트 윈도우(context window)와 출력 토큰(output tokens)을 조정하는 것입니다. Gemma4 모델들은 에이전트 작업을 위해 권장되는 자체 파라미터가 있습니다. qwen의 경우 다음과 같이 테스트했습니다:

FROM qwen3.5:9b

# 코딩 작업을 위한 설정: 낮은 온도, 제한된 컨텍스트
...

모델을 생성하려면:

ollama pull qwen3.5:9b
ollama create qwen-coding -f Modelfile

어떤 모델을 선택할지에 대해, 32GB RAM을 갖춘 GPU가 없는 Linux 환경에서의 제 경험은 다음과 같습니다:

• 9B (Qwen) 모델이 합리적인 최소 사양입니다. 예열(warm up)하는 데 1분 이상 걸리고 속도는 느리지만, 작은 작업들을 처리하고 레포지토리(repo)에 관한 질문에 답변할 수 있습니다.
• 4B 모델은 환각 (hallucination) 현상이 통제 불능 수준입니다. 내용을 지어내고 대화의 흐름을 계속해서 이탈시킵니다.
• Mac 환경이라면 27/30B 모델을 사용할 수 있으며, 이는 성능 면에서 Haiku와 Sonnet 사이 어딘가에 위치합니다.

Pi는 소형 모델(small models)에 있어 Claude Code보다 결정적인 장점을 하나 가지고 있습니다. Claude Code의 시스템 프롬프트 (system prompt)는 수천 줄에 달하며 수많은 도구 (tools)를 포함하고 있는데, 이는 소형 오픈 모델들을 압도 (overwhelms) 해버립니다. Pi의 미니멀리즘 (minimalism)이야말로 소형 모델들이 제대로 작동할 수 있게 만드는 핵심입니다.

기차 안이나 어디에서든 오프라인 상태로 있으면서도, 에이전트 (agent)에게 요청하는 것만으로 레포지토리에 대해 질문하고 변경 사항을 적용할 수 있다는 점은 매우 특별한 경험입니다.

요약

**테스트 벤치 (test bench)**로서의 Pi는 타의 추종을 불허합니다. 모델이 수행하는 모든 것을 볼 수 있고, 동작을 비교할 수 있으며, 더 무거운 하네스 (harness) 환경에서는 시작조차 못 할 오픈 소스 및 로컬 모델들을 실행할 수 있습니다. 에이전트를 단순히 사용하는 것을 넘어, 에이전트가 내부적으로 어떻게 작동하는지 이해하는 데 관심이 있다면 주말 동안 직접 구축해 볼 가치가 충분합니다. 단, 반드시 **컨테이너 내부 (inside a container)**에서 실행하세요. 관심이 있으시다면, github에 로컬 모델을 위한 이 설정이 담긴 작은 리포지토리를 준비해 두었습니다.

언제나 그렇듯, 이곳이나 github에 댓글을 남겨주시거나 bluesky를 통해 메시지를 보내주세요. 여러분만의 Pi 설정을 구축하신다면, 그 결과가 어떠했는지 꼭 듣고 싶습니다.