durable-harness는 Pi, OpenCode, Claude Code, Codex를 Vercel, Postgres, 또는 로컬 노트북에서 내구성 있게 실행해 줍니다. 크래시나 타임아웃이 발생해도 에이전트 세션이 끊기지 않고 이어집니다.
개발자라면 Pi, Claude Code 같은 하네스로 코딩 에이전트를 로컬에서 돌려 본 경험이 있을 겁니다. 매일 코드를 생성하는 데는 믿고 쓸 만하지만, 에이전트를 24시간 가동하려면 컴퓨터를 계속 켜 두고 절전 모드에 들어가지 않게 해야 합니다. 노트북 덮개를 닫지 못하게 하는 밈과 Mac mini 수요 급증도 여기서 나왔습니다.
하네스 워크로드는 점점 클라우드로 옮겨 가고 있습니다. 개인 개발자가 상시 가동되는 코딩 에이전트 워크플로를 배포하고, OpenWork나 HanaAgent 같은 프로젝트는 오픈소스 하네스를 앱의 엔진으로 활용하며, 엔지니어들은 자체 하네스 제품을 만들고 있습니다.
이런 하네스는 세션을 메모리에 유지하는 장시간 프로세스를 전제로 설계되었고, 에이전트 작업은 보통 몇 분에서 몇 시간씩 걸립니다. 로컬에서는 하네스가 같은 디스크의 워크스페이스와 세션 기록에 곧바로, 끊김 없이 접근할 수 있어서 중단된 작업도 간단한 프롬프트 하나로 재개할 수 있습니다.
클라우드에서도 VM과 영구 스토리지로 같은 환경을 꾸밀 수는 있습니다. 하지만 VM은 어떤 모델 호출과 도구 호출이 끝났는지 자동으로 기록하지 않고, 크래시 후 중단된 턴을 이어서 실행해 주지도 않습니다. 턴이 실패하거나 네트워크 오류가 나면 그동안의 작업은 사라집니다.
또한 하네스로 실행하는 에이전트 작업이 모두 샌드박스를 필요로 하는 것은 아닙니다. 데이터베이스 쿼리나 API 호출은 함수 안에서 안전하게 실행할 수 있고, 그러면 필요한 자격 증명을 샌드박스에 넘길 일도 없습니다.
Vercel은 eve와 fx를 별도 설정 없이 클라우드에서 내구성 있게 실행되도록 만들었습니다. 이번에 소개하는 durable-harness은 이 내구성을 Pi, OpenCode, Codex, Claude Code를 포함한 모든 하네스로 확장합니다. Workflow SDK를 구동하는 것과 같은 기반 기술을 사용하므로 크래시나 함수 타임아웃이 발생해도 세션이 유지됩니다.
durable-harness으로 할 수 있는 일은 다음과 같습니다.
Vercel에서 원하는 하네스를 내구성 있게 실행
직접 운영하는 Postgres 인스턴스로 하네스를 셀프 호스팅
로컬 하네스 워크플로를 내구성 있게 전환
나만의 내구성 있는 하네스 구축
코딩 에이전트가 기존 앱에 가격 페이지를 추가하는 상황을 예로 들어 보겠습니다. 에이전트는 기존 페이지를 읽고, 새 페이지를 작성하고, 풀 리퀘스트를 연 다음, CI가 끝날 때까지 기다렸다가 결과를 보고합니다.
CI가 아직 돌고 있는데 함수가 타임아웃되면 어떻게 될까요?
아래 데모에서 함수를 종료하거나 연결을 끊어 보면서 두 에이전트가 어떻게 복구하는지, 어떤 작업이 반복되는지 비교해 보세요.
내구성이 없으면 에이전트는 직접 다시 시작해 줄 때까지 멈춰 있고, 이미 끝낸 작업도 불필요하게 반복합니다.
durable-harness을 사용하면 새 함수가 로그에서 완료된 결과를 읽어 와 턴을 이어서 진행합니다. 브라우저 연결이 끊겨도 에이전트는 계속 실행되며, 다시 연결하면 로그를 기준으로 진행 상황을 따라잡습니다.
durable-harness은 Vercel 오픈소스 포트폴리오의 가장 새로운 패키지입니다. 이미 쓰고 있는 하네스가 Workflow SDK의 내구성 백엔드인 World에 세션을 보관할 수 있게 해 주는 어댑터와 유틸리티 모음입니다.
턴의 각 단계는 내구성 있는 로그에 기록됩니다. 모델 호출이나 도구 호출을 실행하기 전에 실행 의도를 기록하고, 호출이 끝나면 결과를 기록합니다. 턴 자체는 큐 메시지로 보호되므로, 함수가 중간에 죽더라도 큐가 턴을 새 함수에 넘기고, 새 함수는 로그를 읽어 중단된 지점부터 이어서 진행합니다.
크래시가 나면 로그를 통해 무엇이 끝났고, 무엇이 실행 중이었고, 무엇이 아직 시작되지 않았는지 알 수 있습니다.
완료된 호출은 결과를 로그에서 읽어 오므로 다시 실행되지 않습니다. 따라서 끝난 모델 호출의 토큰 비용이 두 번 청구되는 일도 없습니다.
모델은 이전 호출을 반복하지 않고 기억해 둡니다.
중단된 도구 중 replay: 'safe'로 표시된 것은 다시 실행됩니다. 그 밖의 도구는 실행되었을 가능성이 있다는 정보와 함께 모델에 전달되고, 확인할지는 모델이 판단합니다.
Claude Code의 트랜스크립트, Codex의 롤아웃, OpenCode의 이벤트 저장소처럼 자체 세션 파일을 유지하는 하네스는 모든 기록이 로그에 미러링되므로, 새 함수나 Sandbox가 로그로부터 세션 파일을 다시 만들어 냅니다.
fx와 eve는 자체적으로 내구성을 갖추고 있습니다. 나머지 하네스에는 durable-harness이 하네스를 수정하지 않고 외부에서 내구성을 더해 줍니다.
하네스별 전체 설정 가이드는 문서를 참고하세요.
내구성 있는 에이전트에는 각 단계를 기록하는 로그, 프로세스가 죽었을 때 턴을 재개하는 방법, 지켜보는 사람을 위한 스트림이 필요합니다.
Workflow SDK는 이 세 가지를 World라는 하나의 인터페이스로 제공합니다.
durable-harness은 이 인터페이스를 기준으로 동작하므로, 코드를 바꾸지 않고도 같은 에이전트를 다른 World로 옮길 수 있습니다.
Vercel에서는 Vercel World를 사용합니다.
개발 환경에서는 내 컴퓨터의 파일을 사용합니다.
직접 운영하는 서버에서는 Postgres, MongoDB, Redis, Turso 중 하나를 사용합니다.
변수 두 개만 설정하면 durable-harness을 사용하는 모든 에이전트를 Postgres로 옮길 수 있습니다.
네임스페이스를 지정하거나 서버 시작 시 세션을 복구하는 등 더 세밀하게 제어하려면 코드에서 World를 직접 만들어 에이전트에 전달하면 됩니다.
자세한 내용은 셀프 호스팅 문서를 확인하세요.
Vercel의 Agent Runs는 모든 모델 호출과 도구 호출을 포함해 세션별 트레이스를 보여 줍니다. 크래시 후 재개된 턴도 같은 트레이스에 나타나므로, 턴이 어디서 멈췄고 어디서 다시 시작했는지 정확히 알 수 있습니다.
에이전트는 사용자가 지정해 준 도구만 쓸 수 있고, 이 도구들은 사용자의 함수 안에서 실행됩니다. 각 도구에는 크래시로 중단되었을 때 어떻게 처리할지를 지정합니다. 조회처럼 'safe'로 지정한 도구는 다시 실행해도 됩니다. 반면 환불처럼 'never'로 지정한 도구는 절대 두 번 실행되지 않습니다. 대신 모델에 호출이 이미 실행되었을 수 있다고 알려 주므로, 모델이 다시 시도하기 전에 먼저 확인할 수 있습니다.
위 데모의 코딩 에이전트라면 도구를 다음과 같이 정의할 수 있습니다.
파일을 읽거나 CI 상태를 확인하는 도구는 'safe'로 표시해 자동으로 다시 실행되게 합니다.
PR 댓글을 남기는 도구는 'never'로 표시해 댓글이 중복 게시되지 않게 합니다.
다음은 환불을 처리하는 에이전트를 예로 들어, 정책별로 도구를 하나씩 정의한 코드입니다.
셸이나 파일 편집처럼 하네스에 기본 내장된 도구는 아래에서 이어서 설명합니다.
하네스에 셸과 파일이 필요할 때, 공유 서버리스 함수 호스트에서 직접 실행하는 것은 안전하지 않습니다. 여러 세션이 같은 함수를 공유할 수 있고, 함수의 파일 시스템은 호출 사이에 유지된다는 보장이 없기 때문입니다.
durable-harness은 이 문제를 해결하기 위해 몇 가지 선택지를 제공합니다.
virtual()는 파일을 세션 로그에 보관하며, 함수의 파일이나 네트워크에는 접근할 수 없는 bash 호환 셸을 제공합니다. 샌드박스 전체를 띄우지 않고도 짧은 작업이나 작은 워크스페이스를 처리하기에 적합합니다.
virtual({ durable: false })는 임시 작업용으로 파일을 메모리에 보관하고, 매 턴이 끝날 때마다 지웁니다.
sandbox()은 세션 전용 Vercel Sandbox를 제공하고, /workspace은 모든 샌드박스와 함수보다 오래 유지되는 Drive에 마운트됩니다. 실제 프로젝트나 장시간 작업에 적합합니다.
세 가지 방식의 차이는 문서에서 한눈에 비교할 수 있습니다.
각 하네스의 내장 도구는 사용자가 선택한 워크스페이스에서 실행됩니다. Pi의 경우 CodingTools이 Pi 고유의 read, write, edit, bash를 설치하고, virtualEnv()나 sandboxEnv()가 이 도구들에 워크스페이스를 제공합니다.
OpenCode는 워크스페이스를 workspace로 전달하고, fx는 fxTools()에 전달합니다. Claude Code와 Codex는 실제 셸과 파일 시스템을 전제로 하고 멀티 테넌트 환경에서는 안전하지 않으므로 항상 Vercel Sandbox에서 실행됩니다. 이들의 내장 도구는 builtins: true로 활성화하면 세션의 Drive에서 동작합니다. 각 하네스의 내장 도구 목록은 하네스 가이드에서 확인할 수 있습니다.
할 일 목록, 계획, 에이전트가 채우는 양식처럼 세션에 속하지만 대화에는 포함되지 않는 상태도 있습니다. 문서(document)는 세션 로그에 저장되는 타입이 지정된 JSON입니다. 그래서 크래시가 나도 유지되고 세션과 함께 이동합니다.
도구는 io.docs을 통해 문서를 편집할 수 있습니다. 편집 내용은 도구의 결과와 함께 로그에 커밋되므로, 문서의 내구성 있는 상태가 도구 호출과 항상 일관되게 유지됩니다.
앱에서도 별도 데이터베이스 없이 같은 문서를 읽고 편집할 수 있으며, 채팅 라우트에서는 모든 변경 사항을 UI로 스트리밍할 수도 있습니다.
사실 앞서 본 virtual() 워크스페이스도 문서를 기반으로 만들어졌습니다. 파일 트리가 세션 로그에 저장된 문서이고, 도구 호출로 인한 변경 사항은 호출 결과와 함께 커밋됩니다.
도구, 파일, 문서에 대한 자세한 내용과 에이전트를 안전하게 지키는 방법도 확인해 보세요.
개발자가 하네스를 고르는 기준은 프롬프트, 도구, 컨텍스트를 어떻게 다루느냐여야 합니다. 크래시에서 어떻게 살아남느냐는 선택 기준이 되어서는 안 됩니다. durable-harness을 사용하면 턴 도중 함수가 사라져도 새 함수가 로그에서 이어받아 계속 진행합니다. 수동으로 재시도할 필요도, 이미 끝난 작업을 반복할 필요도 없습니다. Workflow SDK의 World 인터페이스 위에 구축했기 때문에 셀프 호스팅과 이식성도 별도 설정 없이 바로 사용할 수 있습니다.
durable-harness은 GitHub에서 오픈소스로 공개되어 있습니다.
