가이드

작성자 Matt Connor 2026-08-16

SandBase 에이전트 런타임 직접 호스팅 및 설치 가이드

Q: 런타임을 공용 포트에 노출해도 안전합니까?

기본 설치 상태로는 안전하지 않습니다. 127.0.0.1:3000에 바인딩되며 인증이 꺼진 상태로 시작되는데, 단순히 바인딩 주소를 바꾸는 것만으로는 해결되지 않습니다. API 키를 생성하거나 MANAGED_AGENTS_API_KEY을 설정하여 Bearer 토큰 인증을 활성화하십시오. 그 후 nginx나 Caddy를 앞에 두어 TLS를 적용하고, 방화벽에서 3000번 포트를 닫아 프록시를 통해서만 접근할 수 있도록 하십시오.

Q: 로컬, Docker, Kubernetes 샌드박스의 차이점은 무엇입니까?

local은 런타임 사용자의 권한으로 호스트에서 런타임의 자식 프로세스로 도구 코드를 실행하며, 별도의 격리 기능은 없습니다. docker는 각 세션에 고유한 파일 시스템, 메모리 제한, CPU 점유율을 가진 컨테이너를 할당하며 세션 종료 시 이를 삭제합니다. kubernetes은 세션을 파드로 실행하고 kubectl exec로 제어합니다. 이를 위해서는 런타임 이미지 내부에 kubectl가 필요하며, 대상 네임스페이스에 RBAC 설정과 exec 하위 리소스 권한이 있어야 합니다.

Q: 정확히 무엇을 백업해야 합니까?

워크스페이스 내의 .managed-agents/ 디렉터리를 백업해야 합니다. 여기에는 config.yaml와 에이전트, 세션, 자격 증명 저장소 항목, 메모리 항목이 포함된 data.db SQLite 데이터베이스, 그리고 업로드된 파일, 스킬 패키지, 세션 스냅샷이 저장됩니다. 아카이브 도중 SQLite에 데이터가 기록되는 것을 방지하기 위해 복사 전에는 반드시 서비스를 중지하십시오. ${OPENAI_API_KEY}로 참조되는 제공자 API 키는 백업에 포함되지 않으므로 별도로 보관하십시오.

Q: 왜 main 대신 v0.3.2 태그를 클론해야 합니까?

태그는 고정된 트리이므로 문서에서 읽은 설정 키와 CLI 명령어를 그대로 사용할 수 있습니다. main은 계속 변경되며, 가이드 작성 시점과 실행 시점 사이에 설정 키 이름이 바뀔 수 있습니다. 또한 프로젝트 측은 npm의 범위가 지정되지 않은 managed-agents 패키지가 이 프로젝트가 아니라고 경고하고 있으며, npx managed-agents을 실행하면 전혀 관련 없는 패키지가 설치됩니다. 릴리스 v0.3.1은 주로 해당 npm 빠른 시작 방식을 고정된 태그 소스 경로 방식으로 대체하기 위해 존재합니다.

SandBase Harness v0.3.2를 자체 VPS에 설치하는 방법을 안내합니다. Node.js 22 환경 설정, 에이전트 YAML 구성, MCP 서버 연결 및 Anthropic SDK 연동을 위한 필수 설정과 주의 사항을 상세히 설명합니다.

SandBase 에이전트 런타임을 직접 호스팅할 때 얻는 이점

SandBase 에이전트 런타임을 직접 호스팅한다는 것은 사용자가 소유한 서버에서 SandBase Harness를 실행한다는 의미입니다. 따라서 세션, 자격 증명, 메모리, 감사 추적 데이터가 타인의 서버가 아닌 사용자의 디스크에 저장됩니다. 이 서비스는 Node 기반으로 동작합니다. 127.0.0.1:3000에서 수신 대기하며 /v1 HTTP API와 웹 콘솔을 제공하고, 에이전트 파일 옆의 SQLite에 상태를 유지합니다.

/v1 API는 호스팅형 관리 에이전트 API인 Claude Managed Agents(CMA)를 본떠 설계되었습니다. 바로 이 점이 이 런타임의 양방향 활용성을 높여줍니다. Anthropic SDK를 사용하여 코드를 작성하고 baseURL를 사용자의 서버로 지정할 수 있으며, 나중에 동일한 코드를 그대로 호스팅형 배포 환경으로 옮길 수 있습니다.

SandBase Harness는 모델을 내장하고 있지 않습니다. 대신 외부 모델을 호출합니다. 2026년 8월 기준으로 OpenAI, Anthropic 및 OpenAI 호환 엔드포인트를 지원하며, 여기에는 자체 호스팅 게이트웨이와 DeepSeek V4와 같은 제공업체가 포함됩니다. 사용자는 여전히 API 키를 준비하거나 OpenAI API를 지원하는 로컬 서버를 갖추어야 합니다.

시작하기 전에 필요한 것

최소 2 GB RAM을 갖춘 Ubuntu 24.04 기반 VPS가 필요합니다. TypeScript 빌드는 설치 과정 중 가장 많은 리소스를 소모하는 단계입니다.
Node.js 22 이상 및 npm 10 이상이 필요합니다. 이는 프로젝트에서 명시한 필수 최소 사양입니다.
git 및 사용할 모델 제공업체의 API 키가 필요합니다.
세션별 컨테이너 샌드박스를 사용하려는 경우에만 Docker가 필요합니다.

Ubuntu 24.04의 기본 저장소는 Node 18.19 버전을 제공하는데, 이는 최소 요구 사양보다 낮으므로 NodeSource에서 Node를 설치하십시오.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v

node -v 명령을 실행하면 v22 이상의 버전이 출력되어야 하며, npm -v 명령을 실행하면 10 이상의 버전이 출력되어야 합니다. 만약 node -v 명령에서 여전히 v18.19.1가 출력된다면, 배포판 패키지가 설치되어 PATH에서 우선순위를 점유하고 있는 상태입니다. 빌드는 셸에서 먼저 발견되는 node를 기준으로 실행되므로, 계속 진행하기 전에 해당 패키지를 삭제하십시오.

v0.3.2 태그에서 SandBase 설치하기

항상 태그를 사용하여 설치하십시오. 변경이 잦은 브랜치를 사용해서는 안 됩니다. main를 베어 클론(bare clone)하면 한 시간 전에 커밋된 내용이 포함될 수 있으며, 아래의 설정 키가 일치하지 않을 수 있습니다. 2026년 8월 16일 기준으로 현재 태그는 v0.3.2입니다.

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.2 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

npm install가 아닌 npm ci을 사용하십시오. ci는 커밋된 락파일(lockfile)에 기록된 정확한 버전을 설치하므로, 사용자의 트리와 관리자가 테스트한 트리가 일치하게 됩니다. npm install은 더 최신 버전을 해석할 수 있도록 허용하며, 이로 인해 고정된 태그가 의도치 않게 변경될 수 있습니다.

이제 워크스페이스를 생성하십시오. 워크스페이스는 에이전트 파일과 모든 런타임 상태를 보관하는 별도의 디렉터리입니다. 소스 체크아웃 외부에서 관리하면 데이터를 건드리지 않고도 더 최신 태그를 가져올 수 있습니다.

mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js start

init은 워크스페이스 내부에 .managed-agents/ 디렉터리를 생성합니다. start는 http://127.0.0.1:3000/dashboard에서 콘솔을, http://127.0.0.1:3000/v1에서 API를 실행합니다. 아직 노트북에서 접근할 수 없는 상태가 정상이며, 이에 대해서는 아래에서 자세히 다룹니다. 현재는 SSH를 통해 콘솔에 접속하십시오.

ssh -N -L 3000:127.0.0.1:3000 you@your-server

긴 node .../dist/index.js 경로는 입력하기 번거로우므로 이름을 지정하십시오.

alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'

아래의 명령어는 이를 기준으로 sandbase <command>으로 작성되었습니다.

npm을 통해 설치하지 마십시오

해당 프로젝트의 설치 문서에는 다음과 같은 내용이 명시되어 있습니다. npm에 공개된 스코프가 지정되지 않은 managed-agents 패키지는 이 프로젝트가 아닙니다. 따라서 npx managed-agents 및 npm install -g managed-agents 명령을 실행하면 사용자가 원하는 런타임과 무관한 패키지가 설치됩니다. 관리자가 공식 스코프 패키지를 발표하기 전까지는 태그가 지정된 GitHub 소스에서 직접 설치해야 합니다. 이는 프로젝트 역사에서 가볍게 넘길 수 있는 각주가 아닙니다. v0.3.1 버전이 존재하는 주된 이유는 기존의 npm 퀵 스타트 방식을 고정된 태그 소스 경로로 대체하기 위함입니다.

워크스페이스를 모델 제공자에 연결하기

init은(는) .managed-agents/config.yaml을(를) 작성합니다. 워크스페이스 전체에 하나의 제공자가 설정되며, 개별 에이전트가 구체적인 모델 ID를 선택합니다.

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}
storage:
  metadata:
    provider: sqlite
    options: {}
  artifacts:
    provider: local
    options:
      base_path: files

${OPENAI_API_KEY} 폼은 프로세스 환경에서 값을 가져오므로, 키가 설정 파일에 남지 않으며 해당 파일의 모든 백업본에서도 제외됩니다. systemd는 권한을 낮추기 전에 EnvironmentFile=을(를) root 권한으로 읽으므로, root만 읽을 수 있는 환경 파일에 해당 키를 저장하십시오.

sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.env

해당 파일을 편집기로 열고 OPENAI_API_KEY=sk-... 한 줄을 추가하십시오. 제공자 키는 이곳에 저장해야 합니다. 세션 중에 에이전트가 사용하는 보안 정보는 런타임의 자격 증명 저장소(credential vault)에 저장해야 하며, 이는 영향 범위가 다른 별개의 문제입니다. 프로덕션 토큰을 어느 곳에든 붙여넣기 전에 AI 에이전트에서 보안 정보 제외하기를 읽어보는 것을 권장합니다.

에이전트 YAML: mcp_servers, 도구 및 권한 정책

에이전트는 워크스페이스의 agents/ 디렉터리에 YAML 파일로 정의됩니다. 이곳이 런타임에서 실제로 많은 시간을 보내게 될 영역입니다.

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
metadata:
  template: incident-commander

파일을 로드하고 정상적으로 반영되었는지 확인합니다:

sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"

reload은 시드 YAML을 SQLite로 가져옵니다. list를 실행하면 이제 ID가 포함된 에이전트 정보가 출력되어야 합니다. 만약 list에서 에이전트가 보이지 않는다면 파일이 파싱되지 않은 것이며, 그 이유는 .managed-agents/logs/runtime.log에 기록됩니다.

mcp_servers은 MCP(model context protocol) 엔드포인트를 선언합니다. type: url은 런타임이 다른 곳에서 실행 중인 서버와 HTTP로 통신함을 의미합니다. 따라서 이미 운영 중인 모든 서비스가 이곳에서 작동하며, 런타임과 같은 VPS에서 호스팅되는 MCP 서버도 포함됩니다.

서버를 선언한다고 해서 해당 도구가 에이전트에 자동으로 제공되지는 않습니다. tools 목록이 이 역할을 수행하며, mcp_toolset 항목의 mcp_server_name이 위에서 선언한 name와 일치해야 합니다. 에이전트가 MCP 도구가 존재하지 않는 것처럼 동작한다면, 다른 곳을 확인하기 전에 이 두 문자열이 글자 단위로 일치하는지 먼저 비교하십시오.

agent_toolset_20260401은 내장 도구 세트입니다. 날짜가 포함된 접미사는 스키마 버전이므로, 특정 버전에 고정된 에이전트는 작성 당시의 도구 정의를 유지합니다. default_config는 해당 세트 내 모든 도구에 대한 정책을 설정하며, configs 하위의 각 항목은 예시의 bash과 같이 도구 이름별로 설정을 재정의합니다.

permission_policy은 런타임이 단순 모델 호출 이상의 가치를 제공하는 지점입니다. always_ask은 세션을 일시 중지하고 도구가 실행되기 전에 사람이 승인할 때까지 대기합니다. always_allow는 실행을 허용합니다. bash을 always_ask로 설정하면 에이전트가 사용자의 확인 없이 셸 명령을 실행할 수 없습니다. 이는 Claude Code를 VPS에서 안전하게 실행할 때 적용하는 제어 방식과 동일합니다.

세 가지 샌드박스 모드와 각 모드의 적합한 사용 사례

코드를 실행하는 도구 호출은 샌드박스 내부에서 수행됩니다. 백엔드는 환경별로 선택하며, 환경의 config 객체 내 sandbox_provider를 통하거나 콘솔의 Settings 내 Sandbox 메뉴에서 설정할 수 있습니다. 환경은 POST /v1/environments API를 통해 생성됩니다.

local 모드는 코드를 런타임의 자식 프로세스로서 호스트에서 런타임 자신의 사용자 권한으로 실행합니다. 이 모드는 기본값이며, 사용자가 본인뿐이고 에이전트가 본인이 소유한 파일만 읽는 경우에 적합합니다. 이 모드는 격리 기능을 제공하지 않습니다. 파일을 삭제하는 도구 호출은 사용자의 파일을 삭제하며, /etc/sandbase/runtime.env를 읽는 도구 호출은 사용자의 공급자 키를 읽습니다.

docker 모드는 세션당 하나의 컨테이너를 시작합니다.

{
  "sandbox_provider": "docker",
  "image": "node:22-slim",
  "resources": { "memory": "1g", "cpu": 1 }
}

세션은 고유한 파일 시스템, 메모리 제한, CPU 점유율을 가지며, 세션이 종료되면 컨테이너도 제거됩니다. 본인이 작성하지 않은 코드를 에이전트가 실행하는 즉시 이 모드로 전환하십시오. 이 모드의 비용은 런타임 사용자가 Docker 소켓에 접근할 수 있어야 한다는 점이며, docker 그룹에 속하는 것은 호스트의 root 권한을 갖는 것과 동일합니다. 세션별 컨테이너는 실행당 하나의 컨테이너를 사용하는 자체 호스팅 에이전트 샌드박스와 동일한 형태이므로, 탈출한 프로세스가 도달할 수 있는 범위에 대한 고려 사항도 동일하게 적용됩니다.

kubernetes 모드는 세션 워크로드를 파드(pod)로 실행하며 kubectl exec 및 kubectl cp을 통해 구동합니다. 런타임 이미지에는 kubectl가 포함되어야 하며, 해당 ServiceAccount는 대상 네임스페이스 내에서 파드를 생성, 삭제, 조회, 목록화, 감시할 수 있는 RBAC(역할 기반 접근 제어) 권한과 exec 하위 리소스 권한이 필요합니다. 이 모드는 이미 클러스터를 운영 중인 경우에만 설정할 가치가 있습니다.

런타임이 127.0.0.1에 바인딩되는 이유는 무엇입니까?

인증이 꺼진 상태로 시작하기 때문입니다. 런타임은 최소 하나의 API 키가 존재할 때 bearer-token 인증을 활성화하는데, 새로 설치된 init은 아무런 키도 생성하지 않습니다. 이 기본 설정에서 0.0.0.0에 바인딩하면 셸 도구와 공급자 키를 가진 인증되지 않은 에이전트 런타임이 공용 인터넷에 노출됩니다.

따라서 외부에서 접근 가능하게 하려면 바인딩 주소는 그대로 두고 다음 두 가지 작업을 수행하십시오.

첫째, 인증을 켭니다. 서비스 환경 파일에 MANAGED_AGENTS_API_KEY을 설정하거나, POST /v1/api-keys로 키를 생성하십시오. 이 명령은 secret_key 필드를 한 번만 반환하며 다시는 표시하지 않습니다. 이후 클라이언트는 모든 요청 시 Authorization: Bearer <key>을 전송해야 합니다.

둘째, 앞에 리버스 프록시를 두고 그 지점에서 TLS(transport layer security)를 종료하십시오. 런타임은 설계상 일반 HTTP만 제공하며, 인증서 처리는 다른 도구가 담당할 것으로 예상합니다.

server {
    listen 443 ssl;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

위 설정 중 두 줄은 단순한 장식이 아닙니다. proxy_buffering off은 세션이 SSE(server-sent events)를 통해 스트리밍되기 때문에 중요합니다. 버퍼링이 켜져 있으면 nginx는 버퍼가 찰 때까지 응답을 붙잡아 둡니다. 이 경우 에이전트가 작업하는 동안 콘솔에는 아무것도 표시되지 않다가 작업이 끝난 뒤에야 모든 내용이 한꺼번에 출력됩니다. proxy_read_timeout 3600s은 기본값이 60초이기 때문에 중요합니다. 1분 이상 스트림이 조용해지면 프록시가 중간에 연결을 끊어버리며, 이 실패는 마치 런타임이 충돌한 것처럼 보입니다.

방화벽에서는 22번과 443번 포트만 개방하십시오. 3000번 포트는 닫아 두어야 합니다. 프록시가 루프백을 통해 해당 포트에 접근하므로 외부에서 직접 접속할 필요가 없기 때문입니다.

Anthropic SDK를 로컬 서버로 연결하기

런타임은 CMA 형태의 /v1 인터페이스를 구현하므로, Anthropic SDK 클라이언트는 필드 하나만 변경하여 통신할 수 있습니다.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000'
});

또한 Claude Managed Agents 클라이언트가 전송하는 베타 헤더인 anthropic-beta: managed-agents-2026-04-01 및 anthropic-beta: agent-memory-2026-07-22도 허용합니다. 로컬 런타임에서는 이 헤더들이 선택 사항입니다. 이는 호스팅 환경을 위해 작성된 코드를 로컬에서 수정 없이 실행하기 위해 존재합니다.

호환성은 매우 높지만 완벽하지는 않습니다. 특정 인터페이스가 존재하는지 가정하기 전에 체크아웃 내의 docs/api-matrix.md를 읽어 보십시오. 해당 문서에는 현재의 이벤트-결과 프로토콜 상에서 명시적 등록이 필요한 클라이언트 측 커스텀 도구를 포함하여, 프로젝트 자체의 미지원 영역이 기술되어 있습니다.

일반 HTTP를 사용하는 것도 가능하며, 런타임이 정상적으로 작동하는지 확인하는 가장 빠른 방법입니다.

curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "stream": true}'

정상적인 응답은 지속적으로 도착하는 이벤트 스트림입니다. 연결이 끊기면 전체 턴을 다시 재생하지 말고 마지막으로 확인한 이벤트부터 재개하십시오.

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: EVENT_ID"

이러한 재개 가능한 스트림 덕분에 노트북을 닫아도 세션이 유지됩니다. 이벤트는 서버에 영구 저장되므로, 클라이언트는 유일한 사본을 보유하는 대신 로그를 다시 재생하는 방식을 취합니다.

자격 증명, 메모리, 감사 추적이 디스크에 저장되는 위치

런타임이 소유한 모든 데이터는 작업 공간 내의 .managed-agents/ 아래에 위치합니다.

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/

data.db는 에이전트, 세션, 자격 증명 저장소 항목, 메모리 저장소 항목 및 API 키를 포함한 SQLite 메타데이터입니다.
files/는 업로드된 파일 바이트를 보관하며, skills/은 업로드된 스킬 패키지를 보관합니다.
snapshots/은 세션 작업 공간 스냅샷을 보관하며, sandbox/은 로컬 모드 세션의 작업 디렉터리를 보관합니다.
logs/runtime.log는 어떤 작업이 아무런 반응 없이 실패할 때 가장 먼저 확인해야 할 곳입니다.

자격 증명 저장소는 비밀 정보의 그룹이며, 각각 environment_variable과 같은 auth_type을 사용하여 추가하고 세션 생성 시 vault_ids를 통해 세션에 연결합니다. 메모리 저장소는 고유한 접근 설정과 지침을 가진 memory_store으로 세션에 마운트하는 명명된 항목을 보관합니다. 두 항목 모두 data.db에 저장되며, 이것이 바로 단순 모델 호출과 런타임의 차이점입니다. 즉, 런타임은 세션 간의 정보를 기억하고 발생한 일을 기록합니다.

하나의 디렉터리로 구성되어 있으므로 전체를 한 번에 백업하십시오.

sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbase

먼저 서비스를 중지하십시오. 런타임이 기록 중인 상태에서 SQLite 데이터베이스를 복사하면 복원 시 열리지 않는 파일이 생성될 수 있으며, 이는 정작 복구가 필요한 날에 문제를 일으킵니다. 에이전트 YAML은 git으로 관리하고 상태 데이터는 다른 곳에 저장하고 싶다면, 배포 문서에서 start의 --data-dir를 사용하여 상태 저장 위치를 지정하는 방법을 참조하십시오.

복원 과정은 그 반대입니다. 새로운 서버에서 동일한 태그를 체크아웃하고, 아카이브를 작업 공간에 압축 해제한 뒤 서비스를 시작하십시오. ${OPENAI_API_KEY} 형식을 사용했다면 공급자 키는 아카이브에 포함되지 않으므로, 별도로 안전하게 보관해야 합니다.

systemd에서 실행하기

런타임에 별도의 사용자를 할당하여 로컬 샌드박스 모드에서 호출된 도구가 사용자의 권한으로 동작하지 않도록 합니다.

sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbase

이 내용을 /etc/systemd/system/sandbase.service로 저장합니다.

[Unit]
Description=SandBase Harness runtime
After=network-online.target

[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

프로젝트의 배포 예제는 PATH에서 managed-agents 바이너리를 호출합니다. 태그된 소스 설치 방식은 해당 바이너리를 생성하지 않으므로, ExecStart은 빌드된 진입점을 대상으로 node를 실행합니다.

sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboard

정상적인 결과는 status에서 active (running), curl에서 200가 출력되는 것입니다. 다른 결과가 나오면 먼저 journalctl -u sandbase -n 50을 읽고, 다음으로 .managed-agents/logs/runtime.log을 확인하십시오. enable --now가 중요한 절반을 차지하는데, 이는 수동으로 시작한 프로세스는 재부팅 후 사라지기 때문입니다.

발생하는 문제와 표시되는 메시지

npm run build이(가) npm에서 오류 없이 종료됩니다. 1 GB VPS에서 TypeScript 컴파일이 수행되면 커널의 out-of-memory killer가 이를 중단시킵니다. 이 경우 npm이 아닌 커널 로그에 기록됩니다. journalctl -k | grep -i "out of memory" 명령으로 확인하십시오. 종료된 node 프로세스 이름이 포함된 줄이 출력됩니다. 스왑을 추가하거나, 더 큰 인스턴스에서 빌드한 후 dist/을(를) 복사하십시오.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. 다른 프로세스가 이미 해당 포트를 점유하고 있습니다. sudo ss -lntp | grep 3000 명령으로 해당 프로세스를 확인할 수 있습니다. 해당 프로세스를 중단하거나, --port 3001 플래그를 사용하여 런타임을 시작한 뒤 프록시 설정을 업데이트하십시오.

노트북에서 대시보드가 로드되지 않습니다. 런타임이 루프백 인터페이스에 바인딩되므로 이는 의도된 동작입니다. 위에서 설명한 SSH 터널을 사용하거나 리버스 프록시 설정을 완료하십시오. 키가 생성되기 전까지는 인증이 비활성화된 상태이므로 --host 0.0.0.0 명령으로 이를 수정하려 하지 마십시오.

Docker 샌드박스가 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock 오류로 실패합니다. sandbase 사용자가 docker 그룹에 포함되어 있지 않습니다. sudo usermod -aG docker sandbase 명령으로 문제를 해결하고 서비스를 재시작하십시오. 단, 이 그룹은 호스트의 root 권한을 가지므로 런타임에 별도 사용자를 부여한 목적의 일부가 무효화된다는 점을 유의하십시오.

Kubernetes 샌드박스가 Error from server (Forbidden) 오류로 실패합니다. ServiceAccount에 Pod 권한이나 exec 하위 리소스 권한이 누락되었습니다. kubectl auth can-i create pods/exec -n <namespace> 명령으로 직접 확인하십시오. 결과로 yes 또는 no이(가) 반환됩니다.

API 키를 추가한 후 모든 요청이 401 오류를 반환합니다. 첫 번째 키가 생성되면 인증이 활성화되며, 이는 API뿐만 아니라 콘솔에도 적용됩니다. Authorization: Bearer <key> 헤더를 전송하십시오. 키를 분실했다면 새로 생성해야 합니다. secret_key은(는) 생성 시 한 번만 표시되며 읽을 수 있는 형태로 저장되지 않기 때문입니다.

MCP 서버의 도구가 세션에 나타나지 않습니다. mcp_servers 내 tools 블록의 mcp_server_name 항목이 name과(와) 일치하는지 확인하십시오. 그 후 curl -i <url> 명령을 사용하여 서버에서 해당 URL에 접근할 수 있는지 확인하십시오. URL 방식의 MCP 서버는 네트워크 의존성을 가지며, VPS는 노트북과 이름 해석 및 트래픽 라우팅 방식이 다릅니다.

FAQ

OpenAI나 Anthropic 키 없이 SandBase Harness를 실행할 수 있습니까?

네, OpenAI 호환 엔드포인트가 있다면 가능합니다. 런타임은 OpenAI, Anthropic 및 OpenAI 호환 제공자를 지원하므로 OpenAI API를 사용하는 로컬 서버라면 무엇이든 작동합니다. .managed-agents/config.yaml에서 워크스페이스 제공자를 설정하고 api_key와 엔드포인트를 해당 서버로 지정하십시오. 런타임 자체에는 모델이 포함되어 있지 않으므로 호출에 응답할 대상이 반드시 필요합니다.

런타임을 공용 포트에 노출해도 안전합니까?

기본 설치 상태로는 안전하지 않습니다. 127.0.0.1:3000에 바인딩되며 인증이 꺼진 상태로 시작되는데, 단순히 바인딩 주소를 바꾸는 것만으로는 해결되지 않습니다. API 키를 생성하거나 MANAGED_AGENTS_API_KEY을 설정하여 Bearer 토큰 인증을 활성화하십시오. 그 후 nginx나 Caddy를 앞에 두어 TLS를 적용하고, 방화벽에서 3000번 포트를 닫아 프록시를 통해서만 접근할 수 있도록 하십시오.

로컬, Docker, Kubernetes 샌드박스의 차이점은 무엇입니까?

local은 런타임 사용자의 권한으로 호스트에서 런타임의 자식 프로세스로 도구 코드를 실행하며, 별도의 격리 기능은 없습니다. docker는 각 세션에 고유한 파일 시스템, 메모리 제한, CPU 점유율을 가진 컨테이너를 할당하며 세션 종료 시 이를 삭제합니다. kubernetes은 세션을 파드로 실행하고 kubectl exec로 제어합니다. 이를 위해서는 런타임 이미지 내부에 kubectl가 필요하며, 대상 네임스페이스에 RBAC 설정과 exec 하위 리소스 권한이 있어야 합니다.

정확히 무엇을 백업해야 합니까?

워크스페이스 내의 .managed-agents/ 디렉터리를 백업해야 합니다. 여기에는 config.yaml와 에이전트, 세션, 자격 증명 저장소 항목, 메모리 항목이 포함된 data.db SQLite 데이터베이스, 그리고 업로드된 파일, 스킬 패키지, 세션 스냅샷이 저장됩니다. 아카이브 도중 SQLite에 데이터가 기록되는 것을 방지하기 위해 복사 전에는 반드시 서비스를 중지하십시오. ${OPENAI_API_KEY}로 참조되는 제공자 API 키는 백업에 포함되지 않으므로 별도로 보관하십시오.

왜 main 대신 v0.3.2 태그를 클론해야 합니까?

태그는 고정된 트리이므로 문서에서 읽은 설정 키와 CLI 명령어를 그대로 사용할 수 있습니다. main은 계속 변경되며, 가이드 작성 시점과 실행 시점 사이에 설정 키 이름이 바뀔 수 있습니다. 또한 프로젝트 측은 npm의 범위가 지정되지 않은 managed-agents 패키지가 이 프로젝트가 아니라고 경고하고 있으며, npx managed-agents을 실행하면 전혀 관련 없는 패키지가 설치됩니다. 릴리스 v0.3.1은 주로 해당 npm 빠른 시작 방식을 고정된 태그 소스 경로 방식으로 대체하기 위해 존재합니다.

#ai-agents #mcp #self-hosting #sandboxing#anthropic-sdk