<a name="readme-top"></a>
<div align="center">
<img src="https://assets.openhands.dev/logo-whitebackground.png" alt="OpenHands logo" width="340">
<h1 align="center" style="border-bottom: none">Agent Canvas</h1>
<p align="center">
<strong>코딩 에이전트 및 자동화를 위한 자체 호스팅 개발자 제어 센터입니다.</strong></strong>
</p>
<p align="center">
OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode 또는 모든 ACP-호환 에이전트를 로컬, 원격 및 클라우드 백엔드에서 실행하세요.
</p>
</div>
<div align="center">
<a href="https://github.com/OpenHands/incubator-program"><img src="https://img.shields.io/badge/status-beta-blue?style=for-the-badge" alt="Project status beta"></a>
<a href="https://github.com/OpenHands/OpenHands/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/OpenHands/OpenHands/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
<a href="https://www.npmjs.com/package/@openhands/agent-canvas"><img src="https://img.shields.io/npm/v/%40openhands%2Fagent-canvas?style=for-the-badge&logo=npm" alt="npm version"></a>
<a href="https://docs.openhands.dev/openhands/usage/agent-canvas/backends"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Documentation"></a>
<a href="https://go.openhands.dev/slack"><img src="https://img.shields.io/badge/Slack-Join%20the%20community-611f69?logo=slack&logoColor=white&style=for-the-badge" alt="Join us on Slack"></a>
</div>
<div align="center">
<a href="#quickstart">빠른 시작</a> |
<a href="./docs/README.md">문서(Docs)</a> |
<a href="./docs/SELF_HOSTING.md">자체 호스팅(Self-Hosting)</a> |
<a href="https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents">ACP 에이전트</a> |
<a href="https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations">자동화(Automations)</a> |
<a href="https://go.openhands.dev/slack">Slack</a>
</div>
<p align="center">
<img src="https://assets.openhands.dev/screenshot/automation-preview.png" alt="Agent Canvas automation preview" width="100%"></p>
<hr>
OpenHands Agent Canvas는 코딩 에이전트를 자체 호스팅(self-hosted)되고 항상 작동하는 엔지니어링 팀으로 변환합니다. 이는 Slack에 게시되는 보고서 생성이나 GitHub 이슈를 작업 단위로 자동 분해와 같은 일상적인 작업을 시작하고 자동화하기 위한 개발자 제어 센터입니다.
기본적으로 사용자의 장치에서 로컬로 실행되지만, Docker 컨테이너, VM(가상 머신), 또는 회사 인프라 내에서 에이전트를 실행하는 등 여러 “에이전트 백엔드(agent backends)”에 연결할 수 있습니다. 선택적으로 OpenHands Cloud나 OpenHands Enterprise 인프라에서 에이전트를 실행하도록 설정할 수도 있습니다.
Agent Canvas는 오픈 소스인 OpenHands 에이전트를 기본으로 작동시키지만, Claude Code, Codex, Gemini CLI, Pi, OpenCode와 같은 타사(third-party) 에이전트도 사용할 수 있습니다.
| |
|---|
| 직접 호스팅하기 | 에이전트를 로컬, Docker, VM 또는 에이전트 서버 백엔드를 실행할 수 있는 모든 곳에서 실행 |
| ... | |
질문이나 피드백이 있으시면 GitHub 이슈를 열거나 Slack의 #proj-agent-canvas 채널에 참여해 주세요.
빠른 시작(Quickstart)
OpenHands는 노트북, Mac Mini와 같은 전용 컴퓨터, 또는 클라우드 서버 등 어떤 장치에서든 에이전트를 실행할 수 있도록 설치할 수 있습니다.
OpenHands를 실행하는 가장 강력한 방법은 클라우드 서버에서 하는 것입니다. 이렇게 하면 노트북이 꺼져 있어도 에이전트가 계속 실행될 수 있으며, Slack, GitHub, Datadog와 같은 타사 서비스를 통해 에이전트를 트리거하기가 더 쉬워집니다. 보안 강화(security hardening)에 관해서는 SELF_HOSTING.md를 참조하세요.
특히 주목할 만한 점은, 백엔드를 _여러 다른 환경(multiple different environments)_에서 실행할 수 있으며, 동일한 Agent Canvas 프런트엔드에서 그 사이를 전환할 수 있다는 것입니다. 예를 들어, 코드 리뷰 및 의존성 업데이트를 수행하는 에이전트를 위해 팀과 Agent Server를 공유하고, 개인 에이전트는 노트북에서 실행하도록 할 수 있습니다.
옵션 1: 샌드박스 없이 (Without a Sandbox)
[!WARNING]
이 방법은 설치하는 장치에 에이전트 서버를 직접 실행합니다. 따라서 에이전트는 파일 시스템 전체에 접근할 수 있습니다!
필수 조건: Node.js 24 이상, uv
npm install -g @openhands/agent-canvas
agent-canvas
agent-canvas 명령어는 기본적으로 전체 로컬 스택을 시작합니다. 필요에 따라 일부만 분리하여 실행할 수도 있습니다:
agent-canvas --frontend-only
agent-canvas --backend-only
옵션 2: Docker 샌드박스와 함께 (With a Docker Sandbox)
필수 조건:
- Docker: macOS/Windows용 Docker Desktop, 또는 Linux용 Docker Engine/Docker Desktop.
- 에이전트가 접근하길 원하는 프로젝트 폴더를 포함하는
PROJECTS_PATH 전역 디렉토리. 컨테이너 시작 전에 이를 생성해야 합니다.
macOS / Linux:
export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"
...
Windows (PowerShell / Windows Terminal): 동등한 명령어는 README.windows.md를 참조하세요.
에이전트는 PROJECTS_PATH 아래의 모든 프로젝트에 접근할 수 있게 됩니다.
옵션 3: 여러 Docker 샌드박스와 함께 (With Multiple Docker Sandboxes)
새로운 대화는 각각의 Docker 컨테이너에서 자체 Agent Server와 도구와 함께 실행됩니다. 이는 여러 에이전트를 동시에 실행하는 데 유용합니다. Canvas와 외부 Agent Server는 호스트에서 실행되며 컨테이너로 대화 요청을 라우팅합니다.
사전 요구 사항: Node.js 24 이상, uv, 그리고 실행 중인 Docker Desktop (macOS) 또는 Docker Engine/Desktop (Linux). Canvas를 시작하는 사용자는 docker 명령어를 실행할 수 있어야 합니다.
macOS / Linux:
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas
http://localhost:8000에 접속하여 새로운 대화를 시작하세요. 기존의 로컬 대화는 변환되지 않습니다. 각 컨테이너는 자신의 작업 공간과 지속된 상태를 마운트하므로, 작업 공간 파일과 대화 기록은 컨테이너 교체 후에도 유지됩니다. 동일한 호스트 작업 공간을 사용하는 대화는 여전히 해당 파일을 공유합니다. 충돌하는 편집을 방지하려면 별도의 디렉토리나 작업 트리를 선택하세요.
이 설정은 대화 실행을 격리할 뿐, 전체 Canvas 또는 자동화 서비스를 샌드박스 안으로 이동시키는 것은 아닙니다. Windows의 경우 README.windows.md를 참조하세요.
옵션 4: 소스에서 실행 (From Source)
[!경고]
이 방법은 에이전트 서버를 설치하는 장치에 직접 실행합니다. 즉, 에이전트는 사용자의 파일 시스템에 완전한 접근 권한을 갖게 됩니다!
사전 요구 사항: Node.js 24 이상, npm, uv (agent 서버를 uvx로 실행하기 위함)
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
...
npm/소스 런처는 http://localhost:8000에서, Docker 이미지는 http://localhost:8000/canvas에서 접속할 수 있습니다. UI를 통해 추가 백엔드를 직접 추가할 수 있습니다.
로컬 환경(npx / npm run dev)에서 리스너는 루프백 주소(127.0.0.1)에만 바인딩되므로, 자동 주입되는 세션 키가 네트워크상의 다른 기기에서는 접근할 수 없습니다. 모든 인터페이스에서 리스닝하려면 --host 0.0.0.0을 전달하거나 (OH_BIND_HOST 설정) 할 수 있습니다. 이 경우 세션 키는 주입되지 않으며, UI는 --public과 동일한 API-키 입력 화면을 사용합니다.
Docker는 모든 컨테이너 인터페이스에서 리스닝하므로 포트 발행이 가능하지만, 기본적으로 세션 키를 HTML에 주입하지 않습니다. 위의 퀵스타트는 127.0.0.1로 호스트 포트를 발행하는 동시에 명시적으로 주입을 활성화합니다. 만약 Docker를 LAN 또는 공용 인터페이스에서 발행한다면, AGENT_CANVAS_ALLOW_LAN_SESSION_KEY를 생략하고 UI에 API 키를 입력하십시오. LOCAL_BACKEND_API_KEY를 강력한 값으로 설정하거나, docker exec <컨테이너> sh -c 'cat "$STATE_DIR/api-key.txt"' 명령어로 생성된 값을 검색할 수 있습니다. 인터넷에 노출되는 설치의 경우 셀프 호스팅을 따르십시오.
아키텍처 (Architecture)
Agent Canvas는 단일 머신에서 여러 에이전트를 실행하기 위한 REST API인 OpenHands Agent Server를 기반으로 합니다. 각 Agent Server는 단일 호스트/포트에서 실행되며, Agent Canvas는 여러 Agent Server에 연결하고 그 사이를 쉽게 전환할 수 있습니다.
Agent Server는 다음 어디서든 실행할 수 있습니다:
- 노트북에서 직접 (주의!)
- Mac Mini와 같은 전용 기기
- 클라우드의 가상 머신
- OpenHands Cloud 내부 (당사의 상업적 서비스)
Agent Server는 종종 Automation Server와 함께 사용되는데, 이는 스케줄에 따라 또는 이벤트에 반응하여 실행되는 에이전트를 설정할 수 있게 해줍니다.
<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />
리포지토리 경계 (Repository boundaries)
Agent Canvas는 여러 개의 리포지토리를 가진 OpenHands 시스템의 일부입니다. 변경 사항은 해당 동작을 소유한 리포지토리로 보내야 합니다:
| Repository | Responsibility |
|---|
OpenHands/OpenHands | Agent Canvas 프론트엔드, 사용자 대상 제어 센터, 백엔드 선택 및 로컬 스택 오케스트레이션. |
| ... | |
Agent Server API는 SDK에 의해 구현되며, Agent Canvas의 TypeScript 클라이언트를 통해 사용됩니다. 자동화 서비스가 작업 실행 시점을 결정하고 대화를 Agent Server/SDK로 전송하며, 이는 무엇이 실행될지 결정합니다. 기여자별 경계 및 필요한 사용자 지정 코드 검토 가이드라인은 AGENTS.md를 참조하십시오. | |
더 많은 문서
