OpenHands (Agent Canvas)
- 추천0
- GitHub 별94K
- 개발라이선스MIT
셀프 호스팅 에이전트 관제 화면. OpenHands · Claude Code · Codex 등을 로컬 · Docker · 클라우드에서 돌리고 자동화해요
요약
셀프 호스팅 에이전트 관제 화면. OpenHands · Claude Code · Codex 등을 로컬 · Docker · 클라우드에서 돌리고 자동화해요
설명

Agent Canvas
코딩 에이전트와 자동화를 위한 셀프 호스팅 개발자 관제 센터.
OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, 그리고 ACP를 지원하는 모든 에이전트를 로컬, 원격, 클라우드 백엔드 어디서든 돌려요.
빠른 시작 | 문서 | 셀프 호스팅 | ACP 에이전트 | 자동화 | Slack

OpenHands Agent Canvas는 코딩 에이전트를 셀프 호스팅 방식의, 항상 켜져 있는 엔지니어링 팀으로 바꿔 줘요. 대화를 시작하고 일상 작업을 자동화하는 개발자 관제 센터예요. 예를 들어 Slack에 게시되는 보고서를 만들거나, GitHub 이슈를 작업으로 자동 분해할 수 있어요.
기본값은 내 컴퓨터에서 로컬로 실행하는 것이지만, 여러 개의 "에이전트 백엔드"에 연결할 수도 있어요. 예를 들어 Docker 컨테이너나 VM, 회사 인프라 안에서 에이전트를 돌릴 수 있어요. 원하면 OpenHands Cloud나 OpenHands Enterprise 인프라에서 에이전트를 돌리는 것도 선택할 수 있어요.
Agent Canvas는 오픈소스 OpenHands 에이전트를 바로 실행하고, Claude Code, Codex, Gemini CLI, Pi, OpenCode 같은 서드파티 에이전트도 쓸 수 있어요.
| 기능 | 설명 |
|---|---|
| 원하는 방식으로 셀프 호스팅 | 로컬, Docker, VM 등 에이전트 서버 백엔드를 돌릴 수 있는 어디서나 에이전트를 실행해요 |
| 여러 백엔드 사이 전환 | 집중이 끊기지 않게 로컬, 원격, 클라우드 에이전트를 오가요 |
| 자동화 만들기 | Slack, GitHub, Linear 등과 이어지는 자동화와 워크플로를 만들어요. 일정에 따라, 또는 웹훅 이벤트에 반응해 실행해요 |
| 쓰던 도구와 연동 | 자동화를 Slack, GitHub, Notion 같은 서드파티 서비스와 연결해 워크플로를 자동화해요 |
| 내 모델 가져오기 | 어떤 LLM과도 함께 써요 |
| 어떤 에이전트든 사용 | OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, 또는 Agent-Client Protocol(ACP)을 지원하는 모든 에이전트와 함께 써요 |
질문이나 의견이 있으면 GitHub 이슈를 열거나 Slack의 #proj-agent-canvas 채널에 참여해 주세요.
빠른 시작
OpenHands는 어느 컴퓨터에든 설치해 에이전트를 돌릴 수 있어요. 노트북, Mac Mini 같은 전용 컴퓨터, 클라우드 서버 모두 가능해요.
가장 강력한 방법은 클라우드 서버에서 돌리는 거예요. 노트북을 덮어도 에이전트가 계속 돌고, Slack, GitHub, Datadog 같은 서드파티 서비스로 에이전트를 실행시키기도 쉬워져요. 자세한 내용, 특히 보안 강화는 SELF_HOSTING.md를 보세요.
특히 백엔드를 _서로 다른 여러 환경_에서 돌리면서, 같은 Agent Canvas 화면에서 전환할 수 있어요. 예를 들어 코드 리뷰와 의존성 업데이트를 맡는 에이전트용 Agent Server는 팀과 공유하고, 개인 에이전트는 내 노트북에서 돌릴 수 있어요.
옵션 1: 샌드박스 없이
경고: 설치하는 컴퓨터에서 agent-server를 직접 실행해요. 에이전트가 내 파일 시스템 전체에 접근할 수 있어요!
준비물: Node.js 24 이상, uv
npm install -g @openhands/agent-canvas
agent-canvas
agent-canvas 명령은 기본으로 로컬 스택 전체를 시작해요. 일부만 따로 실행하고 싶으면 나눠서 쓸 수도 있어요.
agent-canvas --frontend-only # static frontend + ingress only
agent-canvas --backend-only # agent server + automation backend + ingress only
--frontend-only: 정적 프런트엔드와 ingress만 실행해요--backend-only: 에이전트 서버, 자동화 백엔드, ingress만 실행해요
옵션 2: Docker 샌드박스로
macOS/Windows에는 Docker Desktop을, Linux에는 Docker Engine이나 Docker Desktop을 설치하세요. Windows 사용자는 PowerShell 빠른 시작을 따라 하세요.
아래 단계는 macOS와 Linux용이에요. 이름 있는 Docker 볼륨에 설정, 비밀값, 대화가 저장되고, 프로젝트는 /projects에 마운트돼요.
1. 작업 폴더 준비
export PROJECTS_PATH="$HOME/projects" # directory containing your project folders
mkdir -p "$PROJECTS_PATH"
Linux Docker Engine에서는 컨테이너 안의 uid 10001이 작업 폴더와 그 안의 기존 파일을 읽고 쓸 수 있어야 해요. 시스템에 맞는 소유권이나 ACL로 그 사용자에게 권한을 주세요. 모든 로컬 사용자와 공유해도 괜찮은 전용 작업 폴더라면 다음 방법도 있어요.
find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} +
find "$PROJECTS_PATH" -type f -exec chmod a+rw {} +
이 명령은 호스트의 모든 사용자에게 작업 폴더 접근 권한을 줘요. ~/.openhands나 다른 민감한 데이터와는 따로 두세요. macOS/Windows의 Docker Desktop은 바인드 마운트 권한을 알아서 처리하므로 보통 이 명령이 필요 없어요.
2. Agent Canvas 시작
docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v openhands-state:/home/openhands/.openhands \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.40.0 # x-release-please-version
http://localhost:8000/canvas를 여세요. 컨테이너를 지워도 상태를 유지하려면 openhands-state를 다시 쓰세요. 새 볼륨에는 기존 ~/.openhands 데이터가 들어 있지 않아요. docker volume inspect openhands-state로 확인하거나 백업하세요.
Linux 권한 문제 해결과 기존 상태 사용
시작할 때 Permission denied가 나오면 오류에 적힌 경로의 접근 권한을 확인하세요. SELinux 호스트에서는 바인드 마운트에 :z 또는 :Z 라벨이 필요한지 확인하세요. 이름 있는 볼륨 대신 기존 ~/.openhands 상태를 바인드 마운트한다면, uid 10001이 그 디렉터리, 기존 키 파일, 자동화 데이터베이스에 접근할 수 있어야 해요. 키는 비공개로 유지하면서 소유권이나 ACL로 권한을 주세요. 상태 디렉터리를 모든 사용자가 쓸 수 있게 만들면 다른 로컬 사용자가 세션 키를 바꿔치기할 수 있으니, 그 경로에는 재귀적인 전체 쓰기 권한을 쓰지 마세요.
기본 컨테이너 사용자를 그대로 두세요. 바꾸면 브라우저 설정 디렉터리에 접근하지 못할 수 있어요. 사용자를 바꾼다면 쓸 수 있는 XDG_CONFIG_HOME을 설정하고, 상태와 작업 폴더 마운트에 접근할 수 있게 하세요.
참고: 엔트리포인트는 Agent Server가 약 30초 동안
/alive확인에 응답하지 않으면 종료 코드 1로 컨테이너를 멈춰요. 그래서 모든 요청에 502를 돌려주는 컨테이너가 남지 않고, 충돌이나 멈춤이 눈에 보이게 실패해요. 자동으로 복구하려면 재시작 정책이 필요해요.--rm대신--restart unless-stopped를 쓰거나, Docker Compose에서는restart: unless-stopped를 쓰세요.
에이전트는 PROJECTS_PATH 아래의 모든 프로젝트에 접근할 수 있어요.
옵션 3: 여러 Docker 샌드박스로
새 대화마다 자기만의 Agent Server와 도구가 든 Docker 컨테이너를 따로 써요. 여러 에이전트를 동시에 돌릴 때 좋아요. 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: 소스에서 실행
경고: 설치하는 컴퓨터에서 agent-server를 직접 실행해요. 에이전트가 내 파일 시스템 전체에 접근할 수 있어요!
준비물: Node.js 24 이상, npm 11.12.1(저장소가 고정한 버전), uv(uvx로 에이전트 서버를 실행하는 데 필요해요)
의존성을 설치하기 전에 npm --version을 확인하세요. 7일 릴리스 보류 필터(npm install --min-release-age=7)는 npm 11.10 이상이 필요하고, 그보다 낮은 버전은 적용하지 않아요. 커밋된 락 파일 그대로 설치하려면 npm ci를 쓰세요. 이 npm 요구 사항은 기여자가 의존성을 풀 때만 해당하고, 배포된 Canvas 패키지를 설치하는 데는 필요 없어요.
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm ci
npm run dev
npm/소스 실행기는 http://localhost:8000에서, Docker 이미지는 http://localhost:8000/canvas에서 화면에 들어가요. 백엔드는 화면에서 바로 추가할 수 있어요.
로컬(npx / npm run dev) 리스너는 루프백(127.0.0.1)에만 열려요. 자동으로 넣는 세션 키가 네트워크의 다른 컴퓨터에서 보이지 않게 하려는 거예요. 모든 인터페이스에서 받으려면 --host 0.0.0.0을 붙이거나 OH_BIND_HOST를 설정하세요. 그러면 세션 키는 주입되지 않고, 화면은 --public과 같은 API 키 입력 화면을 써요.
Docker는 포트 공개가 되도록 모든 컨테이너 인터페이스에서 받지만, 기본으로는 세션 키를 HTML에 넣지 않아요. 위 빠른 시작은 호스트 포트를 127.0.0.1에만 공개하면서 주입을 명시적으로 켠 거예요. Docker를 LAN이나 공개 인터페이스에 공개한다면 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY를 빼고 화면에서 API 키를 입력하세요. LOCAL_BACKEND_API_KEY는 강한 값으로 설정하거나, 생성된 값을 docker exec 컨테이너이름 sh -c 'cat "$STATE_DIR/api-key.txt"'로 가져오세요. 인터넷에 여는 설치는 셀프 호스팅 안내를 따르세요.
아키텍처
Agent Canvas는 OpenHands Agent Server로 움직여요. 한 컴퓨터에서 여러 에이전트를 돌리는 REST API예요. Agent Server 하나는 호스트/포트 하나에서 돌고, Agent Canvas는 여러 Agent Server에 연결해 쉽게 오갈 수 있어요.
Agent Server는 어디서든 실행할 수 있어요.
- 내 노트북에서 직접(조심하세요!)
- Mac Mini 같은 전용 컴퓨터에서
- 클라우드의 가상 머신에서
- OpenHands Cloud(상용 서비스) 안에서
Agent Server는 보통 Automation Server와 짝을 이뤄요. 일정에 따라, 또는 이벤트에 반응해 돌아가는 에이전트를 설정할 수 있게 해 줘요.
저장소 경계
Agent Canvas는 여러 저장소로 이뤄진 OpenHands 시스템의 일부예요. 변경은 그 동작을 맡은 저장소로 보내야 해요.
| 저장소 | 맡은 일 |
|---|---|
OpenHands/OpenHands | Agent Canvas 프런트엔드, 사용자용 관제 센터, 백엔드 선택, 로컬 스택 구성 조율 |
OpenHands/software-agent-sdk | Python SDK, Agent Server, 에이전트, 도구, 대화, 워크스페이스, 이벤트, 표준 서버 API |
OpenHands/typescript-client | Agent Server API용 브라우저 호환 TypeScript 클라이언트 |
OpenHands/automation | 자동화 정의, 일정, 웹훅, 실행 기록, 디스패치 |
Agent Server API는 SDK가 구현하고, Agent Canvas가 TypeScript 클라이언트로 사용해요. 자동화 서비스는 언제 작업을 돌릴지 정하고 대화를 Agent Server/SDK로 보내요. 무엇을 돌릴지는 Agent Server/SDK가 정해요. 기여자용 경계와 꼭 따라야 할 맞춤 코드 리뷰 가이드는 AGENTS.md를 보세요.
더 많은 문서
- 문서 색인
- 아키텍처 개요
- 개발 가이드. 호스트 앱에 Canvas 컴포넌트를 내장하는 방법도 있어요(컴포넌트 import 옆에서
@openhands/agent-canvas/styles.css를 한 번 불러오세요) - 셀프 호스팅 가이드
라이선스
MIT 라이선스예요. 자세한 내용은 LICENSE를 보세요.
평점
- 5점
- 0
- 4점
- 0
- 3점
- 0
- 2점
- 0
- 1점
- 0