FootprintAI/Containarium: 오픈 소스 기반의 자체 호스팅 가능한 에이전트 네이티브 샌드박스

오픈 소스이며, 자체 호스팅(self-hostable)이 가능하고, 에이전트 네이티브(agent-native)인 샌드박스입니다.
Cursor, Claude Code, OpenCode, 또는 귀하의 자체 MCP 클라이언트와 같은 에이전트를 가져오세요. — 저희가 박스(box)를 실행합니다.

agent: "'blog'라는 이름의 샌드박스를 만들어줘" → containarium create
agent: "접속할 수 있도록 SSH를 연결해줘" → containarium ssh-config sync
agent: "박스 내부의 :8080 포트에 Caddy를 설치해줘" → shell_exec (agent-box MCP를 통해)
...

🎬 전체 55초 데모 시청: youtu.be/IBDDD_tb8FY · 🌐 라이브 데모: helloworld.demo.containarium.dev

AI 에이전트는 점점 더 개발 인프라의 주요 사용자가 되고 있습니다. 에이전트들은 구축, 설치, 배포 및 검증을 원합니다. 하지만 인간의 노트북(너무 소란스럽고, 너무 위험하며, 너무 로컬 환경임)이 아니라 다음과 같은 특성을 가진 샌드박스에서 수행하기를 원합니다:

지속성 (Persistent): 에이전트 실행 간에도 상태(state)가 유지됩니다.
격리성 (Isolated): 잘못된 설치 작업이 귀하의 기기에 영향을 주지 않습니다.
실제 환경 (Real): systemd, 실제 네트워킹, 그리고 오픈 인터넷에 무언가를 호스팅할 수 있는 능력을 갖춘 완전한 Linux 환경을 제공합니다.
구조화된 도구에 의한 구동 (Driven by structured tools): 명령어가 화면 밖으로 스크롤되어 사라지지 않기를 바라며 TTY에 명령어를 입력하는 에이전트 방식이 아니라, MCP를 통해 타입이 지정되고(typed), 경계가 정해지며(bounded), 안전하게(safe) 작동합니다.

이것이 Containarium이 제공하는 박스입니다. Containarium은 자체 호스팅되는 단일 호스트 플랫폼(하나의 VM → 여러 개의 격리된 LXC 컨테이너)으로 실행되며, MCP를 통해 관리 인터페이스(admin surface)를 노출합니다. 또한 컨테이너 내부에서 실행되는 두 번째 MCP 서버를 함께 제공하여, 에이전트가 직접 shell_exec를 수행하고 파일을 편집할 수 있도록 합니다.

에이전트를 가져오세요. 저희가 박스를 실행하겠습니다.

curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install.sh \| sudo bash

이 명령은 Containarium + Incus + 종속성(dependencies)을 설치하고, 데몬(daemon)을 시작하며, http://localhost:8080에서 작동하는 API를 제공합니다.

sudo containarium create alice --ssh-key ~/.ssh/id_ed25519.pub
sudo containarium list

containarium ssh-config sync
# ~/.containarium/ssh_config에 항목을 추가합니다.
# 그 다음 ~/.ssh/config에 한 줄을 추가하세요:
...

~/.cursor/mcp.json 또는 ~/.claude.json 파일에:

{
"mcpServers": {
"containarium-box": {
...

이제 Claude Code, Cursor, 또는 MCP를 지원하는 모든 에이전트가 Alice의 컨테이너 내부에서 직접 shell_exec, read_file, write_file, list_directory, move_file, delete_file을 호출할 수 있습니다.

containarium expose-port alice \
--container-port 8080 \
--domain blog.example.com

Sentinel 상의 Caddy가 blog.example.com에 대한 TLS를 종료(terminate)하고 alice-container:8080으로 전달합니다. curl https://blog.example.com을 실행하면 Alice가 8080 포트에서 서비스 중인 내용에 접속됩니다.

Containarium의 모든 동작은 CLI 동사(canonical)와 MCP 도구(동일한 Go 함수로 위임하는 얇은 래퍼(thin wrapper))를 모두 가집니다. 컨벤션(convention)은 CLAUDE.md를 참조하세요.

모든 컨테이너 내부에서 실행됩니다. stdio를 통해 도달하며(일반적으로 클라이언트 측에서 SSH로 래핑됨), Linux 네이티브 작업을 노출합니다:

도구	기능
shell_exec	셸 명령어를 실행하고 stdout/stderr/exit를 캡처하며, 타임아웃(기본 30초, 최대 10분) 및 256 KiB 출력 제한이 적용됨
read_file	바이트 범위(Byte range) 또는 head=N 줄 또는 tail=N 줄 읽기
write_file	mkdirp를 사용한 원자적 쓰기 (temp + rename)
list_directory	유형/크기/수정 시간(mtime), 숨김 파일 필터링
move_file	목적지에 mkdirp를 적용한 원자적 이름 변경
delete_file	단일 파일 삭제 (디렉토리는 거부되므로, 재귀적 삭제는 영향 범위(blast radius)가 명시적인 shell_exec를 통해 수행됨)

선택적 샌드박스(sandbox): AGENTBOX_ROOT가 설정되면, 모든 파일 작업(file-ops) 경로는 경계 인식 접두사 체크(boundary-aware prefix check)와 함께 해당 루트를 기준으로 해결(resolved)됩니다. 기본값은 설정되지 않음 = 제한 없음입니다. Go 구현체는 internal/agentbox/를 참조하세요.

호스트에서 실행됩니다. 컨테이너 외부의 관리 작업을 노출합니다: create_container, list_containers, delete_container, start_container, stop_container, expose_port, get_metrics, get_system_info. cmd/mcp-server/를 참조하세요.

플랫폼 MCP와 동일한 인터페이스를 제공하며, 더 깊은 수준의 관리 기능을 포함합니다. 최상위 동사(verbs)는 다음과 같습니다:

containarium create  새 컨테이너 생성
containarium list     모든 컨테이너 목록 표시
containarium delete  컨테이너 삭제
...

전체 옵션을 확인하려면 containarium <verb> --help를 실행하세요.

Sentinel(센티넬)은 다음과 같은 역할을 수행하는 항상 켜져 있는 작은 VM(GCP 프리 티어의 e2-micro 급)입니다:

• 22번 포트로 SSH 수신 (sshpiper가 사용자 이름을 기반으로 올바른 백엔드로 라우팅).
• 443번 포트로 HTTPS 수신 (TLS-passthrough를 사용하는 Caddy 또는 백엔드 Caddy로의 PROXY-protocol 인식 포워딩).
• 백엔드의 스팟 VM(spot-VM) 종료 시 유지 관리 페이지를 통해 대응.
• 정적 IP / DNS A-레코드를 보유하여 백엔드가 일시적(ephemeral)일 수 있도록 지원.

전체 설계에 대해서는 docs/SENTINEL-DESIGN.md를 참조하세요.

Agent (Cursor / Claude Code / OpenCode)
|
| MCP over stdio
...

단일 Sentinel은 여러 개의 백엔드 VM — 즉 "풀(pool)" — 의 전면에 위치할 수 있으며, 단일 배포(deployment)는 여러 개의 풀(각각 격리됨)을 실행할 수 있습니다. docs/MULTI-POOL.md를 참조하세요.

이러한 서비스들은 AI 에이전트를 위한 샌드박스를 제공하지만, 오직 호스팅된 SaaS 형태로만 제공됩니다:

자체 호스팅 가능성 (Self-hostability): Containarium은 사용자의 자체 인프라(5달러짜리 VM, 홈랩, 기업 데이터 센터 등)에서 실행됩니다. e2b, Modal, Replit은 SaaS 전용입니다. 즉, 사용자의 코드, 데이터, 고객이 그들의 컴퓨팅 자원을 거쳐야 합니다.
라이선스 (License): Apache 2.0, CLA 없음. 포크(Fork)하고, 판매하고, 실행하세요.
표면 (Surface): systemd, 실제 네트워크 네임스페이스(network namespaces), GPU 패스스루(GPU passthrough)를 갖춘 완전한 Linux 컨테이너입니다. 호출당 프로세스 하나를 생성하는 방식의 샌드박스가 아닙니다.
전송 (Transport): MCP를 나중에 덧붙인 커스텀 SDK가 아니라, 첫날부터 MCP 네이티브(MCP-native)로 설계되었습니다.

기존 서비스들은 지속적인 IDE입니다. Containarium은 지속적인 **박스(box)**입니다 — 개발자 중심이 아닌 에이전트 중심이며, IDE를 가정하지 않고, SSH를 API로 사용합니다:

• Containarium 환경은 SSH와 MCP를 통해 접속합니다. 어떤 IDE든 사용 가능합니다 (Vim, JetBrains Remote, VS Code Remote, Cursor의 원격 개발 등 — 원하는 대로 선택하세요).
• 비용: 오픈 소스(OSS) 경로에서는 시간당 과금이 없습니다. 자체 호스팅 비용은 사용 중인 기반 VM 비용뿐입니다.
• 지속성 (Persistence): 컨테이너는 무기한 유지됩니다. Codespaces는 비활성 상태 이후 자동으로 삭제됩니다.

LXC는 애플리케이션 컨테이너가 아닌 시스템(system) 컨테이너입니다. 각 컨테이너는 systemd, 실제 init, 실제 사용자, 실제 패키지 관리자, 실제 sudo를 가집니다. Containarium 컨테이너 내부에서 Docker를 실행할 수 있습니다. 그 반대는 사실상 불가능합니다.

만약 당신의 에이전트가 리눅스 배포판의 절반 정도를 apt install 하거나, /etc 내의 설정 파일을 수정하고, 데이터베이스를 실행하며, 재부팅까지 해야 한다면 — LXC가 적합한 형태입니다. 만약 에이전트가 단일 Python 프로세스만 실행한다면, Docker나 Modal로도 충분합니다.

에이전트 네이티브 프리미티브 (agent-native primitives) 외에도, Containarium은 다음을 제공합니다:

Ubuntu 24.04 LTS (기본값)
Rocky Linux 9 (개발/테스트)
RHEL 9 (프로덕션)
Windows Server VM — QEMU/KVM을 통한 RDP 지원 — docs/WINDOWS-VM-SETUP.md 참조

ML/AI 에이전트 워크플로우를 위해 설계되었습니다. NVIDIA RTX 3090, RTX 4090 및 유사 모델과 호환됩니다. PCI 레벨 패스스루 (PCI-level passthrough)를 지원하여 컨테이너가 GPU를 직접 인식합니다. 터널을 통해 센티넬 (sentinel)에 연결된 베어메탈 (bare-metal) GPU 노드에서 테스트되었습니다.

단일 센티넬은 다음을 전면에 배치할 수 있습니다:

GCP 스팟 VM (spot VMs): 선점 (preemption) 시 자동 복구가 가능한 비용 효율적인 클라우드 백엔드.
베어메탈 GPU 노드: SSH 접속이 가능한 모든 리눅스 장치; 아웃바운드 터널을 통해 센티넬에 도달합니다.
Windows VM: 리눅스 백엔드와 함께 공존합니다.

모든 백엔드의 모든 컨테이너는 단일 통합 API에 나타납니다.

CLI를 입력하는 것을 선호하지 않는 사용자를 위해 /webui/에 기본 대시보드가 제공됩니다:
컨테이너 목록, 생명주기 제어 (lifecycle controls), 메트릭 (metrics), 브라우저 기반 터미널.
세련된 UI는 의도적으로 클라우드 제품의 영역으로 남겨두었습니다 — 오픈 소스 (OSS) 웹 UI는 기능적이며, 특정 방식(opinionated)을 강요하지 않습니다.

컨테이너는 VM 재시작 및 스팟 종료(spot termination) 상황에서도 생존합니다. ZFS가 압축, 스냅샷 (기본적으로 매일 수행, 30일 보관), 그리고 체크섬 (checksums)을 처리합니다.

센티넬 자체는 e2-micro (프리 티어) 사양입니다. 센티넬은 다음을 수행합니다:

• 약 10초 내에 스팟 선점 (spot preemption)을 감지하고 유지보수 페이지를 제공합니다.
• 스팟 VM을 자동으로 재시작합니다 (총 복구 시간 약 85초).
• 고정 IP를 유지하므로 백엔드가 교체되어도 DNS가 변경되지 않습니다.

VictoriaMetrics + Grafana가 자동 프로비저닝됩니다. 컨테이너별 CPU, 메모리, 디스크, 네트워크를 모니터링합니다. 웹훅 (webhooks)을 통한 알림 기능을 지원합니다. 사용자별 SSH 감사 로그 (audit logs)를 제공합니다.

비특권 LXC 컨테이너 (Unprivileged LXC containers): 컨테이너의 루트(root) ≠ 호스트의 루트(root).
사용자별 프록시 계정 (Per-user proxy accounts): /usr/sbin/nologin

sentinel 상에서 사용자는 자신의 컨테이너를 통해서만 프록시(proxy)할 수 있습니다.
사용자별 fail2ban (fail2ban per-user): Alice의 계정에 대한 공격이 Bob을 차단하지 않습니다.
ClamAV + Trivy: 모든 백엔드(backend)에 걸쳐 스캔을 수행합니다.
AppArmor 프로파일 (AppArmor profiles): 컨테이너별로 적용됩니다.
AGENTBOX_ROOT 샌드박스 (AGENTBOX_ROOT sandbox): 런타임(runtime) 시 agent-box의 파일 작업(file ops)을 제한합니다.

# 생성 (Ubuntu 24.04, 기본값)
containarium create alice --ssh-key ~/.ssh/id_ed25519.pub
# 옵션과 함께 생성
...

# 공용 호스트 이름에 컨테이너 포트 노출
containarium expose-port alice \
--container-port 8080 \
...

# stdout으로 출력 (미리보기)
containarium ssh-config show
# ~/.containarium/ssh_config에 작성 (연결을 위한 한 줄 `Include`)
...

# JWT 토큰 발급 (CLI 전용; API를 통해 노출되지 않음)
containarium token generate \
--username admin \
...

curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install.sh \
| sudo bash

스크립트가 수행하는 작업은 hacks/README.md를 참조하세요.

cd terraform/gce
cp examples/single-server-spot.tfvars terraform.tfvars
vim terraform.tfvars # project_id, admin_ssh_keys, allowed_ssh_sources 설정
...

변수에 대한 내용은 terraform/gce/README.md를 참조하세요.

호스트 OS (Host OS): Ubuntu 24.04 LTS 이상 (컨테이너는 지원되는 모든 OS 가능).
Incus 6.19+: Docker-in-LXC 지원을 위해 필요합니다. Ubuntu 24.04의 기본 저장소에는 AppArmor 버그(CVE-2025-52881)가 있는 6.0.0 버전이 포함되어 있으므로, 최신 빌드를 위해 Zabbly Incus 저장소를 사용하세요.
ZFS 커널 모듈 (ZFS kernel module): 디스크 할당량(disk quotas)용.

• 커널 모듈 (Kernel modules):
  overlay, br_netfilter, nf_nat (컨테이너 내 Docker 실행 시 필요).

# Zabbly를 통한 빠른 Incus 설치
curl -fsSL https://pkgs.zabbly.com/key.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/zabbly-incus.gpg
...

Containarium이 제공하는 인터페이스:

REST API: http://localhost:8080 (gRPC 서비스 상의 gRPC-gateway, JWT 인증)
gRPC: :50051 (mTLS, 주로 CLI에서 사용)
두 개의 MCP 서버 (Two MCP servers): mcp-server (플랫폼) 및 agent-box (박스 내부)

OpenAPI / Swagger UI 주소:
http://localhost:8080/swagger-ui/

토큰 발행 (Token-issuance)은 설계상 **CLI 전용 (CLI-only)**입니다. 데몬에는 "API를 통한 토큰 발행" 엔드포인트가 존재하지 않는데, 만약 존재한다면 API 접근 권한이 있는 누구나 관리자 토큰을 생성(mint)할 수 있기 때문입니다.

• 각 사용자는 자신만의 키 쌍 (keypair)을 가집니다.
  절대로 사용자 간에 키를 공유하지 마십시오. 공유할 경우 권한 취소 (revocation), 감사 (audit), 그리고 사용자별 fail2ban 기능이 무력화됩니다.
• 동일한 키로 sentinel 프록시 계정과 컨테이너 모두에 인증할 수 있습니다. 이것이 지원되는 흐름입니다. 프록시 계정은 nologin 상태이며 오직 라우팅 역할만 수행하므로, 사용자에게는 더 간편하면서도 보안 손실은 없습니다.
• 키 교체 (rotate) 방법: 사용자가 새 키를 생성하면, 관리자가 컨테이너 내의 authorized_keys 내용을 교체합니다.

신뢰할 수 없는 에이전트 (untrusted agent)를 실행하는 경우, AGENTBOX_ROOT를 프로젝트 디렉토리로 설정하십시오:

# 컨테이너 내부에서
export AGENTBOX_ROOT=/srv/project
agent-box # 이제 모든 파일 작업은 /srv/project로 제한됩니다

shell_exec는 의도적으로 LXC 컨테이너 경계 자체를 넘어서는 제한을 두지 않았습니다. 이는 설계상 이 도구의 계약 (contract)입니다. 더 강력한 격리 (isolation)가 필요한 경우, 더 제한적인 컨테이너(예: 중첩된 LXC 또는 사용자 계정에 대한 추가적인 chroot)에서 agent-box를 실행하십시오.

• 백엔드 VM은 기본적으로 공인 IP (public IP)가 없습니다. 이들은 Cloud NAT를 통해 외부로 연결하며, sshpiper를 통해서만 인바운드 연결을 허용합니다.
• Sentinel 허용 목록 (allowlist): Terraform에서 allowed_ssh_sources를 구성하거나 (또는 방화벽 규칙을 수동으로 설정하여) 22번 포트에 접속할 수 있는 대상을 제한하십시오.

왜 Docker / Podman을 사용하지 않나요?
Docker는 애플리케이션 컨테이너용입니다. Containarium은 LXC 시스템 컨테이너 (system containers)를 사용합니다. 즉, 컨테이너당 전체 Linux OS, 실제 systemd, 네이티브 SSH를 제공하며, Docker-in-LXC가 작동하고 영구적인 파일 시스템 (persistent filesystem)을 가집니다. 만약 에이전트가 apt install을 수행하고 재부팅해야 한다면, LXC가 필요합니다.

왜 Kubernetes를 사용하지 않나요?
Kubernetes (K8s)는 여러 노드에 걸쳐 애플리케이션 컨테이너를 오케스트레이션 (orchestrate)합니다. Containarium은 하나(또는 소수)의 노드에서 많은 수의 전체 Linux 환경을 실행합니다. 형태가 다르며, 해결하려는 문제도 다릅니다.

왜 Vagrant를 사용하지 않나요?
Vagrant는 개발자의 로컬 머신에서 VM을 오케스트레이션합니다. Containarium은 많은 에이전트를 위해 공유된 원격 인프라 상에 환경을 호스팅합니다.

왜 Dev Containers / VS Code Remote Containers를 사용하지 않나요?
Dev Containers는 프로젝트 범위 내로 한정되며, IDE와 결합되어 있고, 단일 개발자를 대상으로 합니다.
Containarium은 IDE에 구애받지 않으며, 여러 사용자(또는 한 사용자의 여러 에이전트)에게 공유 인프라 상의 고유한 영구적 박스(persistent boxes)를 제공합니다.

왜 Codespaces / Gitpod를 사용하지 않나요?
이들은 브라우저 기반의 IDE-as-a-Service(서비스형 IDE)이며, 시간당 과금 방식이고, 특정 벤더에 종속(vendor-locked)됩니다. Containarium은 자체 호스팅(self-hosted)이 가능하고, 영구적이며, SSH/MCP 기반입니다. 오픈 소스(OSS) 버전에서는 시간당 과금이 없습니다.

왜 e2b / Modal / Daytona를 사용하지 않나요?
가장 유사한 경쟁 모델로, AI 에이전트를 위한 샌드박스(sandboxes)입니다. 이들은 SaaS 전용이며, 일반적으로 호출당 프로세스가 실행되는 단기 실행(short-lived execution)에 최적화되어 있습니다.
Containarium은 자체 호스팅이 가능하고, MCP 네이티브(MCP-native)이며, 완전한 영구적 Linux 박스를 제공합니다. 호스팅 전용이며 휘발성(ephemeral)인 환경을 원한다면 e2b를 선택하고, 자체 호스팅과 영구적인 환경, 그리고 자신의 인프라에 데이터를 두는 것을 원한다면 Containarium을 선택하십시오.