> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 샌드박스 런타임

> 코드 실행 및 도구 사용을 위한 사용자별 영구 샌드박스입니다.

# 샌드박스 런타임

모든 사용자는 재시작 후에도 유지되는 격리되고 지속적인 샌드박스 환경을 갖게 됩니다.

## 지속성

임시 샌드박스와 달리 Myrm 샌드박스는 다음을 유지합니다.

* 설치된 패키지 및 도구
* 파일 시스템 상태
* 환경 구성
* 실행 중인 프로세스(자동 재시작 포함)

## 격리

각 샌드박스는 다음을 통해 격리된 환경에서 실행됩니다.

* 전용 파일 시스템 볼륨
* 네트워크 네임스페이스 격리
* 리소스 제한(CPU, 메모리, 디스크)
* 런타임 시 시행되는 보안 정책
* **6계층 동시성 및 리소스 방어**: 프로세스 수준 RLIMIT 적용(NPROC=512 포크 폭탄 방지, CPU 시간 제한, 가상 메모리 제한, 파일 설명자 제한, 파일 크기 제한) + SubAgent 팬아웃 제한(턴당 최대 3개의 대리인 호출) + 유형별 동시성 세마포(기본값 5) + 단계별 시간 제한 보호(300초) + 메모리 압력 조정 로드 차단 + 컨테이너 수준 cgroup 하드 캡. `resource` Python 모듈은 에이전트가 자체 한도를 확대하는 것을 방지하기 위해 블랙리스트에 추가되었습니다.
* **4레벨 메모리 압력 모니터**: 컨테이너 인식 cgroup v2 감지, 플래핑 방지를 위한 히스테리시스, Pub/Sub 가입자를 통한 조정된 로드 차단, 긴급 시 자동 GC를 통한 실시간 시스템 메모리 모니터링(정상 → 경고 → 위험 → 비상). 프로세스 수준 리소스 추적(RSS/VMS + 512포인트 기록 링 버퍼 + 주문형 힙 프로파일링)과 결합되어 에이전트는 리소스 소진이 문제가 되기 전에 자체 보호합니다.
* **UI 상호 작용 블랙리스트**: 백그라운드에서 실행되는 하위 에이전트의 경우 샌드박스는 UI 인터페이스(`interactive_feedback`, `send_message`)를 차단하여 팝업으로 사용자를 방해하지 않도록 보장하고 백그라운드 작업과 포그라운드 사용자 상호 작용 간의 진정한 물리적 격리를 제공합니다.
* **계층형 프로세스(PID) 한도**: 샌드박스의 프로세스 상한은 결제 권한입니다 — Free 200 / PRO 512 / MAX 1024 — 컨테이너에 자동 적용되고 생성 시 검증되어 요금제와 컨테이너 리소스가 항상 일치합니다. 프로세스 포화는 cgroup 한도(`pids.current`/`pids.max`) 기준으로 2단계 임계값(70% 경고 / 90% 오류), 브라우저 프로세스 귀속, Doctor 패널의 상위 메모리 프로세스 표시와 함께 모니터링됩니다 — "프로세스 테이블이 가득 차서 에이전트가 멈추는" 조용한 장애가 더 이상 없습니다.

### 기본 OS 수준 샌드박스(Docker 필요 없음)

로컬 및 데스크톱 배포의 경우 Myrm은 모든 주요 플랫폼에서 **기본 OS 수준 프로세스 격리**를 제공합니다.

| Platform | Mechanism               | How It Works                                                                    |
| -------- | ----------------------- | ------------------------------------------------------------------------------- |
| macOS    | Seatbelt (sandbox-exec) | Dynamically generates SBPL profile; Zero-Trust mounts only allow explicit paths |
| Linux    | bubblewrap (bwrap)      | Kernel namespace isolation with PID/network unshare + session separation        |
| Windows  | AppContainer            | Win32 native security token with per-path ACL enforcement                       |

샌드박스 공급자는 시작 시 자동으로 감지되므로 구성이 필요하지 않습니다. 기본 제공자를 사용할 수 없는 경우 시스템은 명확한 경고와 함께 정상적으로 대체됩니다.

**Docker 기반 접근 방식에 비해 주요 이점:**

* Docker 데스크톱 종속성 없음(Windows/macOS에서 설치 마찰 감소)
* 밀리초 미만 시작(컨테이너 이미지 가져오기 없음)
* 기본 OS 보안 기본 요소(사용자 공간 에뮬레이션이 아닌 커널 적용)
* 로컬 WebUI, Tauri 데스크톱 및 클라우드 모드에서 동일하게 작동합니다.

### 제로 레이턴시 에이전트 시작

에이전트 실행은 요청 수신 후 30ms 이내에 토큰 생성을 시작합니다.

* **로컬/데스크톱**: 작업 공간 설정(mkdir + 실행기 바인딩)에 15ms 미만 소요 — LLM RTT 측정 오류 내
* **클라우드**: 미리 준비된 샌드박스 풀은 사용자 요청이 도착하기 전에 컨테이너가 준비되도록 보장합니다. 콜드 스타트 지연은 없습니다.
* **도구 초기화**: 첫 번째 실행 후 캐시됨(`_tools_initialized` 플래그) — 후속 메시지는 완전히 건너뜁니다.
* **MCP 연결**: 글로벌 싱글톤 영구 연결 풀 - 메시지 간 재연결 오버헤드 없음
* **TTFT 모니터링**: 지속적인 성능 검증을 위한 내장형 `benchmark_llm_ttft()` 프로브 + `time_to_first_action_seconds` 히스토그램

## 코드 실행

에이전트는 샌드박스에서 직접 코드를 실행할 수 있습니다.

* Python 3.14, Node.js 20, Bun 1.3, 쉘 스크립트
* uv/pip, npm, apt를 통한 패키지 설치
* 파일 읽기/쓰기 작업
* 네트워크 액세스(구성 가능)

### 사전 설치된 데이터 과학 스택(70개 이상의 패키지)

샌드박스에는 가장 일반적으로 필요한 라이브러리가 준비되어 있으므로 설치를 기다릴 필요가 없습니다.

| Category          | Packages                                           |
| ----------------- | -------------------------------------------------- |
| **Data Science**  | pandas, numpy, scipy, scikit-learn, statsmodels    |
| **Visualization** | matplotlib (CJK-ready), seaborn                    |
| **Excel**         | openpyxl, xlsxwriter, xlrd                         |
| **Documents**     | python-docx, python-pptx                           |
| **PDF**           | pypdf, pdfplumber, reportlab, pdf2image, pypdfium2 |
| **Image**         | Pillow                                             |
| **Big Data**      | pyarrow (Parquet/Arrow)                            |
| **Math**          | sympy, mpmath                                      |
| **Utilities**     | httpx, orjson, tqdm, pytz                          |

### Jupyter급 인라인 차트

matplotlib로 생성된 차트는 자동으로 캡처되어 대화에 인라인으로 표시되므로 수동으로 파일을 다운로드할 필요가 없습니다. CJK 글꼴(중국어, 일본어, 한국어)은 기본적으로 올바르게 렌더링되며 빌드 시 확인됩니다.

### 스마트 오류 복구

패키지가 누락된 경우 에이전트는 정확한 설치 명령을 제안하는 실행 가능한 진단 힌트를 자동으로 수신하여 시행착오 루프를 제거합니다.

**자동 언어 라우팅:** 하나의 내장 실행 도구가 입력이 Python인지 셸인지 감지합니다. `python3 -c`에 코드를 래핑하거나 별도의 도구를 선택할 필요가 없습니다. 유효하지 않은 Python은 *실행 전* 명확한 구문 오류로 발견되므로 블라인드 재시도에 더 적은 토큰을 소비합니다.

**경쟁업체 대비:** OpenClaw의 `exec` 도구는 셸 전용입니다. Hermes은 쉘과 Python을 별도의 도구로 분할합니다. Myrm은 GUI 사용자를 위한 하나의 간단한 도구를 유지하고 내부적으로 올바르게 라우팅합니다.

## 업로드된 파일 액세스

메시지에 첨부한 파일(끌어서 놓기 또는 클릭하여 업로드)은 샌드박스 작업 영역에서 자동으로 사용할 수 있습니다.

* **작은 파일**(100KB 미만): 콘텐츠는 즉각적인 분석을 위해 LLM 컨텍스트에 직접 삽입됩니다.
* **대형 파일**(100KB 이상): 에이전트가 `file_read_tool`로 읽거나 코드(예: `pandas.read_csv()`)로 처리할 수 있도록 작업 공간 `_uploaded/` 디렉터리에 자동으로 복사됩니다.

즉, 5MB CSV를 업로드하고 "Python으로 분기별 추세 분석"을 요청할 수 있습니다. 즉, 에이전트는 수동 파일 전송이나 경로 구성 없이 전체 파일에 액세스합니다.

## 작업공간 샌드박스(Git 작업트리 격리)

프로젝트 수준 격리를 위해 모든 채팅 세션에서 **샌드박스 모드**를 활성화하세요.

* **원클릭 토글**: 메시지 입력 툴바에서 '샌드박스' 버튼을 클릭합니다.
* **Git 작업 트리**: 모든 변경 사항이 제한된 격리된 분기를 만듭니다.
* **병합 또는 삭제**: 완료되면 좋은 변경사항을 다시 병합하거나 실험을 삭제합니다.
* **위험 없음**: 명시적으로 병합할 때까지 기본 코드베이스가 수정되지 않습니다.

이는 다음과 같은 경우에 이상적입니다.

* 리팩토링 실험("위험 없이 이 접근 방식을 시도해 보세요")
* 에이전트가 여러 솔루션을 동시에 탐색하도록 허용
* 변경 사항을 수락하기 전에 테스트하려는 코드 검토

**병렬 하위 에이전트 격리**: 다중 에이전트 작업을 실행할 때 각 하위 에이전트는 1GiB 안전 가드가 있는 자체 쓰기 시 복사 작업 영역 복제본(ISOLATED\_COPY 정책)을 얻습니다. 변경 사항은 병렬 실행 후 직렬 순서로 다시 안전하게 병합됩니다. 파일 충돌이나 데이터 손실이 없습니다.

7가지 오케스트레이션 모드(Spawn / Chain / Batch / DAG / Verified / Swarm Fission / Alternatives), 계단식 취소 및 위임 예산을 통해 안전하고 비용 제어가 가능한 병렬 실행을 보장합니다. 3계층 샌드박스(OS 네임스페이스 / Docker 컨테이너 / Workspace COW)는 Docker 종속성 없이 밀리초 만에 시작됩니다. **1,101번의 테스트로 전체 하위 에이전트 및 샌드박스 스택을 검증했습니다.**

**강건성 보장:**

* 로케일 안전: 모든 git 명령은 `LANG=C`을 사용하여 영어가 아닌 시스템에서 구문 분석 실패를 방지합니다.
* 자동 정리: 시작 시 오래된 작업 트리와 고아 샌드박스 분기가 자동으로 정리됩니다.
* Git-invisible: 샌드박스 디렉터리는 `.git/info/exclude`를 통해 `git status`에서 자동 제외됩니다.
* 구조적 오류: 실패는 명확한 진단을 위해 특정 이유(분기 존재, 이미 체크아웃됨, 경로 존재)를 반환합니다.

Claude Code의 CLI 전용 `--worktree` 플래그와 달리 Myrm의 작업 공간 샌드박스는 GUI 토글을 통해 사용할 수 있고 세션 중에 활성화/비활성화할 수 있으며 사전 승인 통합이 포함된 완전한 병합/삭제 워크플로가 포함되어 있습니다.

## Git 및 PR 전달

샌드박스는 Git 워크플로를 **즉시 사용 가능**하게 만듭니다. 완전히 새로운 환경에서도 바로 동작합니다:

* **호스트 한정 푸시 자격 증명**: `GITHUB_TOKEN`이 존재하고 HTTPS `github.com` 원격 저장소로 푸시할 때, Myrm은 인라인 자격 증명 헬퍼를 주입합니다(단, 샌드박스에 기존 자격 증명이 없을 때만). 이 헬퍼는 **호스트 한정**입니다: `github.com` / `www.github.com`에만 응답하며, 토큰은 타사 Git 서버(예: 자체 호스팅 GitLab 원격 또는 원시 HTTPS URL)에 절대 전달되지 않습니다. 토큰은 환경 변수로 참조되며 명령에 절대 인라인되지 않습니다.
* **자동 커밋 신원**: 샌드박스에 전역 `git config user.name/user.email`이 없으면 Myrm이 연결된 GitHub 계정에서 자동 해석합니다(`login@users.noreply.github.com`, `TMPDIR` 캐시 + 5초 타임아웃 + 로컬 폴백). `git commit`이 첫 시도부터 성공합니다 — "Please tell me who you are" 차단이 없습니다.
* **원클릭 PR 전달**: **설정 > 통합 > GitHub**의 GitHub 통합과 함께 사용하세요 — 웹훅 URL이 복사 버튼과 함께 표시되며, 설정한 Webhook Secret이 GitHub에 입력한 값과 일치해야 합니다(페이로드는 `X-Hub-Signature-256`으로 검증). PR 열림 / issue / push 이벤트가 전체 컨텍스트와 함께 채팅으로 돌아옵니다.

결과: "이것을 GitHub에 푸시하고 PR을 열어줘"라고 요청하면 자격 증명, 신원, 이벤트까지 끝까지 동작합니다 — 샌드박스에서 수동 Git 설정이 필요 없습니다.

## 3계층 리소스 관리

샌드박스는 응답성을 최대화하면서 비용을 최소화하기 위해 세 가지 리소스 단계를 거칩니다.

1. **CPU 스로틀** — 짧은 유휴 기간 후에 `ResourceScaler`은 CPU 할당량을 전체 할당의 25%로 줄입니다. 새 작업이 도착하면 `boost_sandbox()`은 콜드 스타트 ​​지연 없이 즉시 전체 CPU를 복원합니다.
2. **절전 모드** — 더 긴 유휴 기간(계획에 따라 다름: 무료의 경우 5분 → Max의 경우 24시간) 후에 `SandboxRecycler`는 컨테이너를 중지하지만 영구 볼륨을 유지합니다. 수면 기간에는 WU 비용이 발생하지 않습니다.
3. **파기** — 장기간 비활성(구성 가능, 기본값 7일) 후에 샌드박스가 완전히 회수됩니다.

**유휴 감지**는 두 가지 보완 신호를 사용하여 오탐지를 방지합니다.

* **역방향 프록시 활동 추적** — 프록시를 통한 모든 사용자 HTTP/WebSocket 요청은 샌드박스의 활동 타임스탬프를 새로 고칩니다(오버헤드를 방지하기 위해 5분당 1개의 DB 쓰기로 제한됨).
* **WebSocket 연결 가드** — 샌드박스에 제어 플레인에 대한 활성 WebSocket 연결이 있는 경우(예: 백그라운드 심층 조사 또는 장기 실행 작업 중) 재활용기는 활동 타임스탬프에 관계없이 절전 모드를 건너뜁니다.

이 이중 신호 접근 방식은 활성 사용자와 백그라운드 작업이 중단되지 않도록 보장하는 동시에 실제로 유휴 상태인 샌드박스를 효율적으로 회수합니다.

## 기업 조직 관리 및 볼륨 핸드오프

B2B 팀의 경우 Control Plane은 전체 조직 수명주기 관리를 제공합니다.

* **RBAC**: 원자적 권한 확인을 통한 소유자/관리자/구성원 역할
* **멱등성 멤버십**: 동일한 사용자를 두 번 추가하면 기존 기록이 안전하게 반환됩니다.
* **원클릭 오프보딩**: 직원이 퇴사하면 관리자가 샌드박스를 동결하고 볼륨을 백업한 후 후임자에게 전송합니다. 이 모든 것이 한 번의 작업으로 이루어집니다.
* **불변의 감사 추적**: 규정 준수를 위해 모든 오프보딩 작업이 기록됩니다.
* **조직 간 보호**: 사용자는 자동으로 두 조직에 속할 수 없습니다.
* **3-웨이 취소 대칭**: 구성원 제거 시 Org MCP / 승인 정책 / 모델 화이트리스트가 즉시 3중으로 비워집니다(fire-and-forget 비동기 푸시). 샌드박스가 절전 중이면 깨어날 때 잔여 거버넌스가 자동으로 정리되어 권한 유령 창이 발생하지 않습니다.
* **아카이브 보존 자동 정리**: 오프보드 아카이브는 조직의 보존 일수(`archive_retention_days`, 기본 365일)에 따라 자동 삭제되어 규정 준수 보존과 디스크 절약을 동시에 달성합니다.
* **전송 안전 경계**: 명시적 `backup_path`는 백업 디렉터리 내부에 있어야 하며(범위 밖은 409 반환), 자체 전송(source == target)은 거부되며, UI는 아카이브가 완료된 구성원만 전송 소스로 표시합니다.

이는 기업 데이터가 퇴사하는 직원에게 절대 유출되지 않음을 의미하며, 완전한 추적성을 통해 조직의 통제하에 유지됩니다.

### 비밀이 전혀 없는 LLM 게이트웨이

클라우드 호스팅 모드에서는 API 키가 샌드박스에 들어가지 않습니다.

* 실제 키는 Control Plane의 **AES-256-GCM SecretsVault**에 저장됩니다.
* 샌드박스는 실제 공급자에 대해 쓸모가 없는 서명된 **가상 키**(`myrm-vk-...`)를 수신합니다.
* 모든 LLM 통화는 가상 키를 확인하고 실제 자격 증명을 삽입하는 CP 릴레이를 통해 라우팅됩니다.
* 요청 본문은 바이트 단위로 스트리밍되어 업스트림 **프롬프트 접두사 캐시**를 완벽하게 보존합니다.
* 완전히 손상된 샌드박스라도 사용 가능한 API 자격 증명을 유출할 수 없습니다.

### 엔터프라이즈 SSO

엔터프라이즈 배포는 OIDC Single Sign-On(Google Workspace, WeCom, Feishu, DingTalk, Azure AD, Okta)을 지원합니다. 직원은 앱을 열고 기업 IdP를 통해 인증합니다. 별도의 등록이나 API 키 관리가 필요하지 않습니다.