ONEDEV

OpenHands

AI Agent OrchestrationCLITypeScript

★ 87,625주당 +801조회 12

무엇인가

OpenHands Agent Canvas는 코딩 에이전트와 자동화 작업을 한 인스턴스에서 시작하고 관리하는 셀프호스팅 제어 센터다. OpenHands 저장소군에서 프런트엔드 계층을 담당하며, 에이전트를 실제로 실행하는 런타임은 별도의 Agent Server로 분리되어 있다. 대화 시작, 백엔드 전환, 스케줄·이벤트 기반 자동화 설정이 이 계층에서 이뤄진다.

어떻게 동작하나

동작의 중심은 OpenHands Agent Server다. Agent Server는 한 머신에서 여러 에이전트를 돌리는 REST API 서버이며 호스트와 포트 하나씩을 차지한다. Agent Canvas는 TypeScript 클라이언트로 이 API를 소비하고, 여러 Agent Server에 동시에 연결해 화면에서 백엔드를 바꿔 가며 쓴다. Agent Server API 자체는 SDK가 구현한다. 스케줄이나 이벤트로 에이전트를 깨우는 Automation Server가 함께 붙는 구성에서는 자동화 서비스가 언제 작업을 돌릴지 정해 대화를 Agent Server/SDK로 넘기고, 무엇을 실행할지는 Agent Server가 결정한다.

무엇과 다른가

구조적 차이는 실행 런타임과 제어 화면의 분리에 있다. 에이전트를 각 머신의 터미널 세션에서 개별적으로 띄우는 방식과 달리, 백엔드를 로컬 노트북, Docker 컨테이너, VM, 사내 인프라, OpenHands Cloud·Enterprise 중에서 고르고 같은 프런트엔드에서 전환한다. 팀 공용 Agent Server는 코드 리뷰·의존성 업데이트에, 개인 Agent Server는 로컬 작업에 동시에 연결하는 식의 분리가 가능하다. 에이전트 종류도 OpenHands 자체 에이전트에 묶이지 않고 Claude Code, Codex, Gemini, ACP 호환 에이전트를 쓸 수 있다.

어떻게 쓰나

설치는 세 가지 경로다. `agent-canvas` 명령이 기본적으로 로컬 스택 전체를 띄우며, 필요하면 구성 요소를 나눠 실행할 수 있다. Docker 샌드박스를 쓰려면 에이전트가 접근할 프로젝트 폴더를 담은 호스트 디렉터리를 PROJECTS_PATH로 지정하고 컨테이너를 시작한다. 소스에서 빌드하는 경로도 있다. npm·소스 실행은 http://localhost:8000, Docker 이미지는 http://localhost:8000/canvas에서 UI에 접속하며 추가 백엔드는 UI에서 직접 등록한다. 자동화는 Slack 보고서 발행, GitHub 이슈를 작업 단위로 분해하는 흐름처럼 스케줄·이벤트에 묶어 설정한다.

전제와 한계

전제 조건은 Node.js 22.12.x 이상과 uv이며, 소스 빌드에는 npm이 추가로 필요하다. Docker 샌드박스 경로는 Docker Desktop 또는 Docker Engine과 PROJECTS_PATH 호스트 디렉터리를 요구한다. 샌드박스 없이 실행하면 agent-server가 설치 머신에서 직접 돌아 에이전트가 파일시스템 전체에 접근할 수 있다. 서버에 올려 상시 가동할 때는 SELF_HOSTING.md의 보안 강화 항목을 따라야 한다. Windows는 README.windows.md의 별도 명령을 쓴다.

유사 도구