Flue: 헤드리스 자율 에이전트를 위한 TypeScript 샌드박스 프레임워크 정리

이 글은 TypeScript 기반 샌드박스 에이전트 프레임워크 Flue가 무엇인지, 어떤 배경에서 등장했는지, 그리고 어떤 아키텍처와 특장점을 통해 자율 에이전트 개발을 표준화하려는지 정리한 글입니다.
단순한 챗봇 수준을 넘어, 코딩 에이전트가 스스로 계획하고 파일을 작성하며 문제를 해결하는 전 과정을 100% 헤드리스·프로그래머블 방식으로 구현하려는 Flue의 접근 방식을 중심으로 설명합니다.

반응형

---

Flue란 무엇인가

**Flue**는 Claude Code나 Codex와 같은 코딩 에이전트의 사용 경험을 순수 코드 기반으로 재구성한 에이전트 하네스 프레임워크입니다.
TUI나 GUI, 혹은 사람 운영자를 전제로 하지 않고, TypeScript 코드만으로 에이전트를 구성해 자율적으로 문제를 해결하고 작업을 완료하도록 설계되었습니다.

Flue의 핵심 개념은 다음 한 문장으로 정리됩니다.

Agent = Model + Harness

이 구조를 통해 단순한 챗봇부터 전체 코딩 플랫폼까지, 다양한 형태의 자율 에이전트와 워크플로우를 표현할 수 있습니다.

---

하네스(Harness) 아키텍처의 의미

Flue가 주목한 지점은 Claude Code나 Codex를 강력하게 만드는 요소가 단순히 모델이 아니라, 그 위에서 작동하는 하네스 구조라는 점입니다.

하네스는 다음과 같은 역할을 담당합니다.

• 문제 해결을 위한 계획 수립
• 필요한 컨텍스트 수집
• 파일 작성 및 수정
• 서브 에이전트 생성
• 역할(Role) 채택
• 반복적인 문제 해결과 세션 관리

Flue는 이러한 하네스 아키텍처를 일반화해, 특정 서비스나 UI에 종속되지 않는 에이전트 개발 방식을 제공합니다.

---

Markdown 중심의 에이전트 구성 방식

Flue의 또 다른 특징은 에이전트 로직의 상당 부분을 Markdown 파일로 정의한다는 점입니다.

• skills
• context
• AGENTS.md

이 파일들을 통해 에이전트의 행동 방식과 역할, 작업 컨텍스트를 정의합니다.
그 결과, 에이전트의 사고 흐름과 실행 로직이 코드와 문서 형태로 명확히 분리되어 가독성과 유지보수성이 높아집니다.

---

4계층 모던 에이전트 아키텍처

Flue는 에이전트를 다음과 같은 4계층 구조로 설계합니다.

1. Model 계층

• 토큰 관리
• 툴 사용
• 프롬프트 구성

2. Harness 계층

• skills
• memory
• sessions

에이전트의 사고와 작업 흐름을 담당하는 핵심 계층입니다.

3. Sandbox 계층

• bash 실행
• 보안 제어
• 네트워크 접근 관리

4. Filesystem 계층

• 파일 읽기(read)
• 파일 쓰기(write)
• 검색(grep, glob)

이 구조를 통해 에이전트는 실제 개발 환경과 유사한 조건에서 안전하게 작업할 수 있습니다.

---

런타임 비종속 설계와 유연한 배포

Flue는 runtime-agnostic 구조를 채택해, 동일한 코드로 다양한 환경에서 실행할 수 있습니다.

• Node.js
• Cloudflare Workers
• GitHub Actions
• GitLab CI/CD

배포 방식 또한 유연합니다.

• 에이전트를 HTTP 서버로 번들링
• 서버 없이 CLI 형태로 직접 실행해 로컬 작업이나 CI 환경에 활용

---

가볍고 확장 가능한 샌드박스 구조

Flue의 기본 샌드박스는 가상 샌드박스 방식으로 동작합니다.
에이전트마다 컨테이너를 생성하지 않기 때문에, 고트래픽 환경에서도 빠르고 비용 효율적으로 확장할 수 있습니다.

또한 다음과 같은 선택지가 제공됩니다.

• 원격 샌드박스 연결
• 별도 설정 없이 사용하는 내장 가상 샌드박스

---

주요 API와 사용 흐름 예시

Flue에서 제공하는 주요 API는 다음과 같습니다.

• init()
• harness.session()
• session.skill()
• session.prompt()
• session.shell()
• session.fs.writeFile()

간단한 사용 흐름 예시

세션을 생성하고, 프롬프트 실행과 파일 작성을 수행하는 기본적인 흐름은 다음과 같습니다.

const app = init();

const session = app.harness.session();

await session.prompt("문제를 분석하고 해결 계획을 세워라");

await session.fs.writeFile(
  "result.md",
  "# 작업 결과\n에이전트가 생성한 결과물입니다."
);

UI 없이도 에이전트의 사고 과정과 실행 결과를 코드로 직접 제어할 수 있다는 점이 Flue의 특징입니다.

---

보안과 토큰 보호 전략

Flue는 민감한 토큰과 API 키를 분리 보호할 수 있도록 설계되었습니다.
에이전트나 샌드박스가 GITHUB_TOKEN과 같은 환경 변수를 직접 접근하지 못하도록 제어할 수 있어, CI/CD 환경에서도 안전한 운영이 가능합니다.

---

“다른 사람의 에이전트를 임대하지 말라”는 철학

Flue는 다음 요소를 모두 직접 소유할 것을 강조합니다.

• 에이전트
• 하네스
• 샌드박스

외부 에이전트에 의존하지 않고, 자신만의 에이전트 실행 환경을 구축하는 것이 Flue가 지향하는 방향입니다.

---

에이전트 개발의 표준을 지향하는 Flue

Flue는 Astro나 Next.js가 웹 애플리케이션 개발 방식을 표준화한 것처럼, 에이전트 개발의 표준 프레임워크를 목표로 합니다.
현재는 Experimental 단계로 API 변경 가능성이 있지만, 자율 에이전트를 제품 수준으로 운영하려는 흐름 속에서 중요한 시도가 되고 있습니다.

---

728x90

Flue는 단순한 에이전트 실행 도구를 넘어, 자율 에이전트를 어떻게 설계하고 운영할 것인가에 대한 구조적인 해답을 제시합니다.

• 헤드리스·프로그래머블 에이전트
• 일반화된 하네스 아키텍처
• 런타임 비종속 실행 환경
• 가볍고 안전한 샌드박스 구조

이러한 특징은 앞으로 코딩 에이전트와 자동화 워크플로우가 개발 인프라의 일부로 자연스럽게 통합되는 데 중요한 기반이 될 수 있습니다.
에이전트를 단순한 실험 도구가 아닌 지속적으로 운영 가능한 소프트웨어로 다루고자 한다면, Flue는 충분히 주목할 만한 프레임워크입니다.

300x250

https://flueframework.com/

Flue — The Agent Harness Framework