AI 튜토리얼

Agentbox를 배포하고 브라우저에서 Claude Code 또는 Codex 실행하는 방법

이 튜토리얼에서는 Agentbox 설치, Claude Code 또는 Codex 계정 연결, 영구 Docker 작업 공간 생성, 코딩 작업 수행, 변경 사항 검토 및 사용량 모니터링 방법을 설명합니다. 또한 소스 빌드, 안전한 원격 액세스, 사설 네트워크 터널, 백업 및 주요 운영 제한 사항도 다룹니다.

2026년 9월 29일약 18분 소요

Agentbox를 배포하고 브라우저에서 Claude Code 또는 Codex 실행하는 방법

Agentbox란 무엇인가요?

Agentbox는 브라우저에서 Claude Code와 Codex CLI를 실행할 수 있는 자체 호스팅 환경입니다. AI 채팅, 터미널, 프로젝트 파일, Git 검토, 계정 관리, 사용량 추적 기능을 하나로 결합하며, 사용자의 자체 서버에서 호스팅되는 영구 워크스페이스를 제공합니다.

서버는 TypeScript 프런트엔드가 내장된 단일 Go 바이너리로 배포됩니다. 애플리케이션 상태와 채팅 기록은 SQLite에 저장하고, 코딩 워크스페이스를 격리하기 위해 Docker 컨테이너를 사용합니다. 영구 디렉터리는 컨테이너 수명 주기와 관계없이 프로젝트 파일, 홈 구성, 공유 리소스를 보존합니다.

Agentbox는 한 기기에서 코딩 작업을 시작한 뒤 환경을 다시 구축하지 않고 다른 곳에서 이어서 작업하려는 경우 특히 유용합니다. 작업 중심의 스트리밍 웹 채팅을 사용하거나 브라우저 터미널을 열어 원래의 Claude Code 또는 Codex CLI로 직접 작업할 수 있습니다.

주요 기능

영구 워크스페이스: 프로젝트 파일, 홈 구성, 공유 파일, 채팅 기록이 서버에 유지됩니다.
두 가지 에이전트 인터페이스: 브라우저 채팅과 원래의 명령줄 도구 사이를 전환할 수 있습니다.
통합 제공 워크플로: 프로젝트를 업로드하거나 복제하고, 작업을 할당하고, 파일을 확인하고, Git diff를 검토한 뒤 결과를 커밋하거나 다운로드할 수 있습니다.
중앙 계정 풀: 관리자는 Claude 및 Codex OAuth 구독, API 키, 릴레이 엔드포인트, 액세스 범위, 이그레스 프록시를 구성할 수 있습니다.
사용량 및 비용 기록: 사용자, 모델, 시간별로 사용량을 필터링하고 토큰, 가격 정보 출처, 지연 시간, 기록된 비용을 확인할 수 있습니다.
재사용 가능한 리소스: 각 사용자에게 모든 워크스페이스에서 /shared로 마운트되는 공유 디렉터리가 제공됩니다. 홈 템플릿, Claude 스킬, MCP 구성도 지원됩니다.
선택적 사설 네트워크 액세스: abox-link 클라이언트는 명시적으로 허용된 저장소, 데이터베이스, 서비스를 클라우드 호스팅 워크스페이스에 노출할 수 있습니다.
반응형 인터페이스: 콘솔은 딥 링크, 라이트 및 다크 테마, 모바일 레이아웃을 지원합니다.

아키텍처 이해하기

브라우저는 HTTP 또는 HTTPS와 WebSocket 연결을 통해 Agentbox 서버에 연결됩니다. 서버는 로컬 Docker API를 통해 워크스페이스 컨테이너를 제어하고 애플리케이션 레코드를 SQLite에 저장합니다. 각 워크스페이스에는 자체 컨테이너와 영구 디렉터리가 있습니다.

하나의 워크스페이스에는 여러 채팅 스레드가 포함될 수 있지만, 해당 워크스페이스에서는 한 번에 하나의 웹 채팅 턴만 실행됩니다. 주요 영구 위치는 /workspace, /home/agent, /shared입니다. 컨테이너 교체 후에도 유지해야 하는 파일은 이 위치 중 하나에 저장해야 합니다.

중요: 영구 파일이 있다고 해서 프로세스까지 영구적으로 유지되는 것은 아닙니다. 터미널 네트워크가 중단된 후 다시 연결하면 tmux 세션을 복원할 수 있지만, 컨테이너를 중지하거나 다시 빌드하면 실행 중인 프로세스가 종료됩니다.

사전 요구 사항

가장 빠른 설치 방법은 systemd가 설치된 Linux 서버를 대상으로 합니다. 릴리스 패키지는 Linux x86_64 및 arm64를 지원합니다.

Ubuntu 22.04 이상 또는 Debian 12 이상에서는 누락된 종속성과 Docker를 자동으로 설치할 수 있습니다.
그 외 Linux 배포판에는 Python 3.9 이상, Git, curl, CA 인증서, 시간대 데이터, 로컬 Docker Engine이 필요합니다.
최초 워크스페이스 이미지 빌드에는 컨테이너 레지스트리, Debian 패키지 저장소, npm에 대한 액세스가 필요합니다.
원격 액세스를 사용하려면 SSH 포워딩이나 리버스 프록시를 사용하지 않는 한 서버 방화벽 또는 보안 그룹에서 TCP 포트 8180을 허용해야 합니다.

사전 빌드 설치에서는 서버에 Go 또는 Node.js를 설치할 필요가 없습니다.

릴리스 설치 프로그램으로 Agentbox 설치하기

1. 설치 프로그램 실행

Linux 서버에 연결한 뒤 다음 명령을 실행합니다.

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

설치 프로그램은 기본적으로 최신 안정 릴리스를 선택합니다. README에서는 v0.1.5를 현재 안정 릴리스로 명시합니다. 해당 버전으로 고정하려면 다음 명령을 사용합니다.

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --version v0.1.5

설치 과정에서는 릴리스 패키지를 확인하고, 고정된 도구 버전으로 워크스페이스 이미지를 빌드하며, 구성을 생성하고, 무작위 관리자 비밀번호를 생성한 뒤 agentbox.service를 시작합니다. 초기 이미지 빌드에는 몇 분이 걸릴 수 있습니다.

2. 콘솔 열기

설치가 완료되면 터미널에 출력된 관리자 비밀번호를 기록합니다. 다음 주소에서 플레이스홀더를 서버 주소로 바꾸어 엽니다.

http://YOUR_SERVER_IP:8180

사용자 이름 boxadmin과 생성된 비밀번호로 로그인합니다. Agentbox를 계속해서 공개적으로 사용하기 전에 HTTPS를 구성하세요.

3. 리버스 프록시로 Agentbox 제한

Agentbox가 로컬 연결만 수락하도록 하려면 설치 중 다음과 같이 수신 대기 옵션을 추가합니다.

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --listen 127.0.0.1:8180

그런 다음 WebSocket을 지원하는 HTTPS 리버스 프록시를 서비스 앞에 배치할 수 있습니다. 릴리스 설치는 /etc/agentbox에 구성을 저장하고 /var/lib/agentbox에 애플리케이션 데이터를 저장합니다.

Claude 또는 Codex 계정 구성

로그인한 후 시스템 설정 → 계정 풀을 엽니다. 현재 중국어 인터페이스에서는 系统设置 → 账号池로 표시됩니다. Claude 또는 Codex 계정을 추가합니다.

Agentbox는 다음 연결 방식을 지원합니다.

Claude 구독: 구독 OAuth를 선택하고 인증 코드를 붙여넣습니다.
Codex 구독: 구독 OAuth를 선택하고 전체 콜백 URL을 붙여넣습니다.
API 또는 릴레이 계정: 제공업체 엔드포인트와 키를 입력합니다. Codex 릴레이는 제공업체가 요구하는 프로토콜과 일치해야 합니다.

식별하기 쉬운 계정 이름과 필요한 경우 이그레스 프록시, 액세스 범위를 설정합니다. 계정은 모든 사용자, 선택한 사용자 또는 관리자만 사용할 수 있도록 지정할 수 있습니다. 관리자는 구성된 모든 계정을 사용할 수 있습니다.

터미널 액세스 권한이 있는 워크스페이스 사용자는 컨테이너 내부의 명령줄 도구에 전달된 자격 증명을 읽을 수 있습니다. 따라서 공유 계정 풀은 신뢰할 수 있는 사용자로 제한해야 합니다. 액세스를 취소하면 새 작업과 자격 증명 동기화가 차단되지만, 완전히 취소하려면 영향을 받는 컨테이너를 중지하고 업스트림 자격 증명을 교체해야 할 수도 있습니다.

첫 번째 워크스페이스 만들기

워크스페이스를 만들고 설명적인 이름을 지정합니다.
에이전트로 Claude Code 또는 Codex CLI를 선택합니다.
사용자에게 사용 권한이 있는 계정을 선택합니다.
Files를 통해 프로젝트를 업로드하거나 Terminal에서 복제하여 가져옵니다.
Chat을 열고 구체적인 코딩 작업을 제출합니다.
편집된 파일을 확인하고 Changes에서 Git diff를 검토합니다.
변경 사항을 로컬에 커밋하거나 프로젝트 파일을 다운로드합니다.

프로젝트 파일 업로드 및 검사

Files 인터페이스는 프로젝트 및 공유 디렉터리에 대한 디렉터리 트리, 업로드, 편집, 미리보기 및 아카이브 다운로드를 제공합니다. 소스 뷰어에는 줄 번호, 구문 강조, 줄 및 열 탐색, 현재 줄 강조 표시, 전체 화면 모드가 포함됩니다.

웹 파일 작업은 제한된 디렉터리 핸들을 사용하며 심볼릭 링크를 따라가지 않습니다. 업로드는 임시 디렉터리에서 검증되고 편집기 저장은 원자적 교체 방식으로 수행됩니다. 하지만 컨테이너 내부의 명령줄 도구는 템플릿에서 제공한 링크를 계속 사용할 수 있습니다.

터미널에서 리포지토리 복제

Terminal을 열고 일반 셸 명령을 실행합니다. 예:

cd /workspace
git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
git status

Agentbox는 워크스페이스 이미지에 원래 에이전트 CLI와 일반적인 개발 도구를 포함합니다. 터미널 세션은 tmux를 사용하므로 브라우저 또는 네트워크 연결이 끊긴 후에도 다시 연결할 수 있습니다.

웹 Chat에서 작업 할당

Chat을 열고 요청한 변경 사항, 관련 제약 조건 및 예상하는 검증 방법을 설명합니다. 예:

이 프로젝트를 검사하고 사용자 등록 엔드포인트에 입력 검증을 추가하세요. 기존 API 응답 형식을 유지하고, 유효하지 않은 이메일 주소에 대한 테스트를 추가한 다음 관련 테스트 모음을 실행하세요.

Chat에서는 모델과 추론 수준을 선택할 수 있습니다. 각 응답에는 시간, 모델, 설정 스냅샷 및 비용이 기록됩니다. Claude는 스트리밍 방식의 헤드리스 턴을 실행합니다. Codex는 앱 서버 통합을 우선 사용하며 핸드셰이크에 실패하면 실행 모드로 대체합니다.

결과 검토 및 전달

에이전트가 작업을 마치면 Changes를 열어 수정된 파일과 색상으로 표시된 diff를 확인합니다. diff만으로 맥락이 충분하지 않으면 전체 파일을 검토합니다.

웹 커밋은 로컬에서 수행되며 원격 리포지토리로 자동 푸시되지 않습니다. Git 훅이나 서명도 실행하지 않습니다. 훅 또는 서명된 커밋이 필요한 경우 터미널을 사용하세요.

Agentbox는 리포지토리 연결, 복제, 가져오기, 빨리 감기 방식의 풀, 미리보기 방식의 푸시, 브랜치 작업, GitHub 또는 GitLab 풀 리퀘스트 및 머지 리퀘스트 생성을 위한 Git 관리 기능도 제공합니다. 리포지토리 연결에는 HTTPS 토큰 또는 SSH 개인 키를 사용할 수 있습니다.

소스에서 빌드 및 실행

Agentbox를 수정하거나 프로젝트에 기여할 계획이라면 소스 워크플로를 사용합니다. 문서화된 빌드 환경은 Docker가 설치된 Linux, Go 1.26.6 또는 호환되는 자동 툴체인, Git, Python 3, curl, iproute2 및 OpenSSL을 사용합니다. 기본 TypeScript 콘솔을 편집할 때만 Node.js 22와 npm이 필요합니다.

1. 복제 및 빌드

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox

go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh

이미지 빌드를 실행하는 사용자는 Docker에 액세스할 수 있어야 합니다. 시작할 때 서버는 마운트된 디렉터리의 소유권도 1000:1000으로 설정해야 합니다. 제공된 systemd 서비스는 root로 실행됩니다.

2. 구성 만들기

cp config.example.json config.json
openssl rand -hex 24

생성된 임의 값을 auth_token에 복사합니다. 초기 테스트에서는 accounts와 proxies를 비워 두고 나중에 Web UI를 통해 실제 계정을 추가합니다.

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

시작하기 전에 플레이스홀더를 교체하세요. 구성 검증에서 플레이스홀더를 거부하기 때문입니다.

3. 서버 시작

sudo ./agentbox -config config.json

localhost에서만 수신하는 서버의 경우 컴퓨터에서 SSH 터널을 만듭니다.

ssh -N -L 8180:127.0.0.1:8180 user@your-server

로컬에서 http://127.0.0.1:8180을 열고 boxadmin 및 구성된 auth_token으로 로그인합니다. 관리자 계정이 생성되면 비밀번호는 SQLite에 저장되며, 이후 auth_token을 변경해도 해당 비밀번호는 초기화되지 않습니다.

4. systemd 서비스 설치

포그라운드 프로세스를 중지한 후 저장소에서 서비스를 설치하고 배포합니다.

sudo ./deploy/install.sh
sudo ./deploy/deploy.sh

첫 번째 스크립트는 서비스와 타이머를 설치합니다. 두 번째 스크립트는 바이너리를 빌드하고 교체한 다음 서비스를 재시작하고 상태를 확인합니다.

사용량 및 비용 모니터링

Usage 페이지에는 모델 활동이 기록되며, 관리자는 사용자, 모델, 시간별로 필터링할 수 있습니다. 개별 기록에는 토큰 사용량, 비용 출처, 지연 시간이 포함됩니다. 일반 사용자는 자신의 기록을 볼 수 있고, 관리자는 모든 사용자의 기록을 볼 수 있습니다.

가격 카탈로그는 models.dev 소스 프리셋 또는 사용자 지정 HTTPS 소스를 사용할 수 있습니다. 가격이 업데이트되어도 이전 스냅샷이 보존되며, 사용자 지정 가격은 보호됩니다. Web 턴에는 해당 턴이 시작될 때 고정된 표의 가격이 적용됩니다.

크레딧 한도는 실시간 하드 캡이 아닙니다. Web 턴은 완료된 후 정산되므로 잔액을 소진시키는 턴에서 초과 사용이 발생할 수 있습니다. 나중에 반영된 터미널 사용량은 기록되지만 크레딧에서 차감되지 않습니다.

고급 팁

워크스페이스 간 공유 리소스 사용

각 사용자의 공유 디렉터리는 해당 사용자의 모든 워크스페이스에서 /shared로 마운트됩니다. 재사용 가능한 스크립트, 참조 파일 또는 아티팩트는 모든 프로젝트에 복사하는 대신 이곳에 저장하세요. Agentbox는 시스템 및 사용자별 홈 템플릿도 지원합니다.

abox-link로 비공개 서비스에 연결

선택 사항인 abox-link 클라이언트를 사용하면 클라우드 워크스페이스에서 컴퓨터 또는 다른 비공개 머신을 통해 접근할 수 있도록 허용 목록에 등록된 서비스에 연결할 수 있습니다. 로컬 패널을 통해 실행하거나 --server를 사용해 명령줄 서버 모드로 실행할 수 있습니다.

허용 목록은 좁게 설정하고 워크스페이스에 필요한 저장소, 데이터베이스 또는 서비스만 노출하세요. Agentbox는 클라이언트와 워크스페이스의 연결 준비 상태를 모두 표시합니다. 일반적인 브라우저 사용에는 abox-link가 필요하지 않습니다.

컨테이너 용량 계획

각 워크스페이스 컨테이너의 기본값은 메모리 2048MiB, CPU 2개, 프로세스 512개입니다. 동시에 실행될 것으로 예상되는 워크스페이스 수에 맞춰 서버 규모를 정하세요. 관리자는 전역 및 사용자별 컨테이너 한도와 예약 디스크 공간도 구성할 수 있습니다.

올바른 데이터 백업

기본 시스템 백업에는 데이터베이스, 구성, 계정 자격 증명, 템플릿 레이어가 포함되지만 워크스페이스 데이터는 제외됩니다. 사용자 파일과 기록도 캡처해야 한다면 agentbox backup --full을 사용하세요. 전체 백업을 수행하려면 먼저 서비스와 관련 컨테이너를 중지해야 합니다. backup-verify로 아카이브를 검증하고 restore --to로 새 디렉터리에 복원할 수 있습니다.

보안 경계 이해

에이전트는 워크스페이스 컨테이너 내부에서 코드를 실행할 수 있습니다. 기본 권한 모드는 bypassPermissions입니다. 컨테이너는 리소스 제한과 no-new-privileges가 적용된 비루트 사용자로 실행되지만, Agentbox 서버 자체는 Docker에 액세스할 수 있습니다. 따라서 배포 및 관리는 신뢰할 수 있는 운영자가 담당해야 합니다.

선택 사항인 원격 브라우저를 신중하게 사용

Agentbox는 영구 로그인 상태, 탭, 전체 화면, 이미지 품질 조정, 클립보드 지원, 다운로드 기능을 포함한 전체 데스크톱 브라우저를 워크스페이스 내부에 제공할 수 있습니다. 관리자는 선택 사항인 agentbox-agent:browser 이미지를 빌드하고 선택해야 합니다. 웹사이트 인증은 Claude 또는 Codex CLI 인증과 별개로 유지됩니다.

기억해야 할 운영상 제한

특정 data_dir는 하나의 Agentbox 프로세스만 사용할 수 있습니다.
현재 운영 아키텍처는 하나의 머신, 하나의 서버 프로세스, 로컬 Docker 데몬으로 구성됩니다.
배포 및 재시작 중에는 연결된 클라이언트의 연결이 잠시 끊깁니다.
원격 Git 상태를 새로 고쳐도 fetch가 수행되지는 않습니다. ahead 및 behind 값은 로컬 캐시에서 가져옵니다.
계정을 폐기해도 이미 실행 중인 컨테이너에 전달된 자격 증명은 제거되지 않습니다.
워크스페이스 컨테이너를 중지하거나 다시 빌드하면 영구 파일은 유지되지만 해당 컨테이너의 프로세스는 종료됩니다.
Git 검토로 중지된 워크스페이스가 시작될 수 있으며, 터미널 액세스와 동일한 크레딧 사용 승인 검사가 적용됩니다.

결론

Agentbox는 Linux 서버를 Claude Code 및 Codex CLI를 위한 영구 브라우저 기반 코딩 환경으로 전환합니다. 릴리스 설치 프로그램으로 시작하고, 계정을 추가하고, 워크스페이스를 생성한 다음, 통합된 Files, Terminal, Changes 뷰를 통해 채팅 작업에서 검토된 코드로 진행하세요. 운영 환경에서는 HTTPS를 추가하고, 계정 액세스를 신중하게 관리하며, 리소스 사용량을 모니터링하고, 필요한 경우 워크스페이스 데이터까지 포함하는 백업 계획을 수립하세요.

더 자세한 구성 및 운영 지침은 Agentbox 저장소, 문서 색인, 배포 및 운영 가이드를 참조하세요.