ScreenEnv: 데스크탑 에이전트를 위한 Docker 기반 풀스택 자동화 환경 (feat. Hugging Face)

9bow · 7월 20, 2025, 3:00오전

ScreenEnv 소개

최근 인공지능 기반의 데스크탑 자동화와 GUI 에이전트 개발에 대한 관심이 높아지고 있습니다. 전통적으로 GUI 테스트나 데스크탑 상의 작업 자동화를 위해선 무거운 가상 머신(VM)을 설정하고, 다양한 운영체제 환경에 대응하는 복잡한 프레임워크를 구성해야 했습니다. 하지만 Hugging Face에서 새롭게 공개한 ScreenEnv는 이 과정을 대폭 간소화하며, 컨테이너 기반으로 데스크탑 환경을 손쉽게 가상화할 수 있도록 도와주는 Python 라이브러리입니다.

ScreenEnv는 Docker 기반의 Ubuntu 데스크탑 환경을 손쉽게 생성할 수 있게 해주는 도구로, GUI를 포함한 풀 데스크탑 세션을 코드로 제어할 수 있도록 설계되어 있습니다. 단순한 마우스 클릭과 키보드 입력뿐만 아니라, 윈도우 창 관리, 파일 조작, 터미널 명령 실행, 그리고 화면 녹화까지 모두 지원합니다. 이 덕분에 복잡한 GUI 기반 응용 프로그램 테스트나 데스크탑 자동화를 위한 에이전트를 매우 빠르게 구축하고 배포할 수 있게 되었습니다.

기존의 데스크탑 자동화 도구들과 비교해 보면, ScreenEnv는 매우 큰 차별점을 가집니다. 대표적인 GUI 자동화 프레임워크인 Selenium이나 AutoIt, PyAutoGUI는 로컬 환경에 직접 접근하거나 제약이 있는 플랫폼에서만 동작할 수 있었습니다. 또한 VM 기반 솔루션은 무겁고 느리며 환경 구축에 시간이 많이 들었습니다.

반면, ScreenEnv는 Docker를 기반으로 하여 몇 초 만에 완전한 데스크탑 환경을 띄울 수 있고, AI 에이전트가 MCP(Model Context Protocol)를 통해 직접 해당 환경과 상호작용할 수 있도록 설계되어 있어 확장성과 통합성이 뛰어납니다. 특히, headless 모드나 직접적인 API 호출, 또는 MCP 서버 방식 등 다양한 통합 옵션을 제공하여, 개발자의 백엔드 구조에 따라 유연하게 적용할 수 있다는 점이 가장 큰 강점입니다.

ScreenEnv의 주요 특징

ScreenEnv의 특징은 다음과 같습니다:

전체 데스크탑 제어: 마우스 및 키보드 조작, 애플리케이션 실행, 창 제어, 파일 관리, 터미널 접근, 화면 녹화 기능 포함
MCP 및 Sandbox API 모두 제공: AI 모델과 통합할 수 있는 MCP 지원과 직접 제어할 수 있는 API 두 가지 방식 제공
Docker 기반 경량 환경: VM이 아닌 Docker 기반으로 빠르게 실행 가능하며, AMD64 및 ARM64 아키텍처 모두 지원

ScreenEnv 설치 및 사용법

설치 방법

ScreenEnv는 pip 명령어로 설치할 수 있습니다:

pip install screenenv

또한, GitHub 저장소를 복제한 뒤, GitHub 저장소의 예제를 실행해볼 수도 있습니다:

git clone https://github.com/huggingface/screenenv.git
cd screenenv
python -m examples.desktop_agent

Docker 권한 문제 발생 시 sudo -E python으로 실행하거나 docker 그룹에 사용자 추가가 필요합니다.

한 줄로 시작

ScreenEnv의 사용은 매우 간단합니다. 다음과 같은 한 줄로 샌드박스를 실행할 수 있습니다.

from screenenv import Sandbox
sandbox = Sandbox()

두 가지 통합 방식

ScreenEnv는 에이전트 프레임워크 또는 백엔드 아키텍처에 따라 두 가지 방식으로 통합할 수 있습니다:

직접 Sandbox API 제어: 보다 세밀한 제어가 필요하거나 커스텀 백엔드와 연동할 때 유용한 방식입니다. 예를 들어, 다음과 같은 방식으로 제어할 수 있습니다:
```
sandbox = Sandbox(headless=False)
sandbox.launch("xfce4-terminal")
sandbox.write("echo 'Custom agent logic'")
screenshot = sandbox.screenshot()
sandbox.close()
```
MCP 서버 방식: MCP를 사용하는 AI 시스템에서 원격으로 컨테이너를 제어할 수 있는 방식입니다. 다음은 원격 제어 예시입니다.
```
from screenenv import MCPRemoteServer
server = MCPRemoteServer(headless=False)
print(server.server_url)
```
이렇게 설정한 뒤, AI 모델이 MCP 프로토콜을 통해 명령을 내려 직접 데스크탑을 제어할 수 있습니다.

ScreenEnv 사용 예시: `smolagents`와 함께 데스크탑 에이전트 만들기

ScreenEnv는 smolagents와의 자연스러운 통합을 지원하여 AI 기반 데스크탑 자동화 에이전트를 간단히 구현할 수 있습니다.

사용할 모델 선택

먼저, 사용할 모델을 선택하고 설정합니다. OpenAI, Hugging Face API, Transformers, Anthropic 등 다양한 백엔드 모델을 연결할 수 있습니다.

from smolagents import OpenAIServerModel
model = OpenAIServerModel(model_id="gpt-4.1", api_key=os.getenv("OPENAI_API_KEY"))

커스텀 에이전트 정의

DesktopAgentBase를 상속받아 클릭, 입력, 실행 등 필요한 기능을 툴로 정의합니다.

@tool
def click(x: int, y: int) -> str:
    self.desktop.left_click(x, y)
    return f"Clicked at ({x}, {y})"

데스크탑 작업 실행

에이전트를 통해 실제 작업을 실행합니다. 다음과 같이 프롬프트를 사용하여 작업을 지정할 수 있습니다.

task = "LibreOffice 열고 ‘AI Agent Workflow in 2025’ 주제로 보고서를 작성하고 저장하라."
result = agent.run(task)

Hugging Face의 ScreenEnv 소개 블로그

Hugging Face의 ScreenEnv GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~