OpenHands

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와 같은 전용 컴퓨터 또는 클라우드의 서버 등 어떤 머신에서든 에이전트를 실행할 수 있습니다.

OpenHands를 실행하는 가장 강력한 방법은 클라우드의 서버에서 실행하는 것입니다. 이렇게 하면 노트북이 꺼져 있어도 에이전트가 계속 실행되며, 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 # 정적 프론트엔드 + 인그레스만
agent-canvas --backend-only # 에이전트 서버 + 자동화 백엔드 + 인그레스만
옵션 2: Docker 샌드박스 사용
사전 요구 사항:

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 "

docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v " $HOME /.openhands:/home/openhands/.openhands " \
-v " ${PROJECTS_PATH} :/projects " \
ghcr.io/openhands/agent-canvas:1.33.0 # x-release-please-version
Windows (PowerShell / Windows Terminal): 동등한 명령은 README.windows.md를 참조하세요.

에이전트는 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이 필요하며, 이전 버전에서는 적용되지 않습니다. 커밋된 lockfile을 재현하려면 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에서 UI에 접근하세요. 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 <container> sh -c 'cat "$STATE_DIR/api-key.txt"'로 생성된 값을 검색하세요. 인터넷에 노출되는 설치의 경우 셀프 호스팅을 따르세요.

아키텍처
Agent Canvas는 단일 머신에서 여러 에이전트를 실행하기 위한 REST API인 OpenHands Agent Server로 구동됩니다. 각 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로 디스패치하며, 이는 무엇이 실행되는지를 결정합니다. 기여자별 경계와 필수 커스텀 코드 리뷰 가이드는 AGENTS.md를 참조하세요.

추가 문서

문서 색인
아키텍처 개요
개발 가이드, 호스트 앱에 Canvas 컴포넌트 임베딩 포함(컴포넌트 임포트 옆에서 @openhands/agent-canvas/styles.css를 한 번 로드)
셀프 호스팅 가이드