AI 튜토리얼

SkyDot 셀프 호스팅 튜토리얼: 처음부터 구축하는 멀티 Dot AI 워크스테이션

이 글에서는 SkyDot의 아키텍처와 핵심 기능을 소개하고, 로컬 설치, 모델 구성, Host 또는 Docker 실행 모드, 데스크톱 클라이언트 연결 및 멀티 Dot 협업 설정을 단계별로 안내합니다.

2026년 11월 11일약 14분 소요

SkyDot 셀프 호스팅 튜토리얼: 처음부터 구축하는 멀티 Dot AI 워크스테이션

SkyDot이란

SkyDot은 Pi Agent Runtime을 기반으로 한 오픈 소스·셀프 호스팅 멀티 사용자 Agent 워크벤치입니다. 이름을 지정하고 구성할 수 있는 여러 Dot을 만들어 각기 다른 역할을 맡길 수 있으며, 여러 Dot을 그룹 채팅에 추가하고 예약 작업, Skills, MCP, Plugins 및 Memory를 통해 장기 실행 능력을 확장할 수도 있습니다.

단순한 채팅 페이지가 아닙니다. Workspace는 파일, 세션, 메모리 및 실행 경계를 구분하고, Backend는 인증, 권한, 큐, 스케줄링, Provider 및 메시지 채널을 처리하며, Host 또는 Docker Runner는 실제 Agent를 실행합니다. 사용자의 확인이 필요한 도구 권한 부여, 디바이스 요청 및 작업 진행 상황도 동일한 워크벤치로 반환됩니다.

핵심 아키텍처와 실행 경계

SkyDot은 인터페이스, 제어 영역 및 실행 영역을 분리하여 개인 사용은 물론 팀의 셀프 호스팅 배포에도 적합합니다.

Backend: Node.js, TypeScript, Hono, SQLite 및 WebSocket을 기반으로 인증, 영속화, 큐, 스케줄링, Provider, 채널 및 권한 부여를 담당합니다.
Runner: Pi Agent Runtime을 사용해 실제 Agent 작업을 실행하며, 로컬 Host 모드 또는 non-root Docker 컨테이너를 선택할 수 있습니다.
Workspace: 파일, Session, Memory, 채널 연결 및 실행 경계를 결정합니다.
Web, PWA 및 Electron: React 비즈니스 프런트엔드를 공유합니다. Electron Renderer는 인터페이스만 담당하며 데이터베이스, 파일 시스템, 자격 증명, Docker 또는 shell/process 권한에 직접 접근하지 않습니다.

한 계층에서 허용되었다고 해서 다른 경계를 자동으로 넘어갈 수 있는 것은 아닙니다. 팀 환경을 배포하기 전에 권한 매트릭스와 보안 정책을 읽어보는 것이 좋습니다.

주요 기능

개인 Dot 및 세션

각 Dot은 이름, 아바타, Prompt, 모델, 사고 수준, Skills, MCP 및 실행 정책을 독립적으로 설정할 수 있습니다. 대화는 스트리밍 출력, Markdown, 코드 블록, 파일 첨부, 중단, 후속 메시지 및 세션 복구를 지원합니다.

서로 다른 Workspace는 격리되므로 동일한 인터페이스에 들어가더라도 파일, 세션, 메모리, 채널 연결 및 실행 권한이 서로 섞이지 않습니다. 실행 시 Host 모드 또는 Container 모드를 선택할 수 있습니다.

멀티 Dot 그룹 채팅 및 협업

기본 그룹 채팅을 활성화하면 동일한 타임라인에서 여러 Dot의 메시지, 작업 응답, 진행 상황 및 결과를 확인할 수 있습니다. 명확한 멘션과 제어된 위임을 통해 협업 범위를 제어합니다. 다시 연결하거나 페이지를 다시 열어도 상태만 읽으며 새로운 작업을 자동으로 제출하지 않습니다.

그룹 채팅은 기본적으로 비활성화되어 있습니다. 기본 그룹 채팅을 활성화하려면 SKYDOT_BOT_GROUPS=true를 설정해야 합니다. Bot 간 협업 실행도 허용하려면 SKYDOT_BOT_HANDOFFS=true를 추가로 설정하고, 관리자가 실행 권한과 호출 예산을 구성해야 합니다.

예약 작업, Skills 및 Memory

Scheduler는 Cron, 고정 간격 및 일회성 작업을 지원하며 즉시 실행, 일시 중지, 취소, 실행 기록 및 결과 전달 기능을 제공합니다. Skills, MCP 및 Plugins를 중앙에서 관리한 다음 Dot별로 활성화 범위를 구성할 수 있습니다.

Memory는 Workspace 단위로 사실, 선호도, 결정, 경험 및 후속 조치 항목을 저장하며 검색, 생성, 편집, 삭제 및 버전 기록을 지원합니다. Session은 구체적인 대화 컨텍스트를 저장하고, Workspace Memory는 여러 Session에서 재사용할 수 있는 지식을 저장합니다. 두 항목은 서로 독립적입니다.

설치 전 준비

Node.js: 22.19 이상 버전, Node.js 24 LTS 권장. Pi Durable 저장소에는 Node.js 내장 SQLite가 필요합니다.
npm: Node.js와 함께 설치되며 각 하위 프로젝트의 의존성을 설치하는 데 사용됩니다.
Docker: Container 실행 모드에서만 필요합니다.
Model Provider: 실제 AI 대화에는 사용 가능한 모델 Provider가 필요합니다. API Key가 없어도 먼저 인터페이스를 시작할 수 있습니다.
GNU Make: 선택 사항이며 타입 검사, 백업 및 운영 명령에 사용됩니다.

처음부터 SkyDot 설치하기

1. 저장소 복제 및 의존성 설치

터미널에서 다음 명령을 실행하여 메인 프로젝트, Web 프런트엔드 및 Agent Runner의 의존성을 각각 설치합니다.

git clone https://github.com/2SinceJuly/SkyDot.git
cd SkyDot

npm install
npm --prefix web install
npm --prefix container/agent-runner install

2. 서비스 빌드 및 시작

의존성 설치가 완료되면 모든 구성 요소를 빌드하고 Backend를 시작합니다.

npm run build:all
npm start

http://127.0.0.1:3000을 열고 페이지의 안내에 따라 관리자 초기화를 완료합니다. Provider와 메시지 채널은 나중에 구성할 수 있지만 모델 설정이 없으면 실제 AI 대화를 실행할 수 없습니다.

3. 개발 환경 시작

개발 중에는 Backend와 Vite Web Client를 동시에 시작할 수 있습니다.

npm run dev:all

개발 페이지의 기본 주소는 http://127.0.0.1:5173입니다. 로컬에서 인터페이스를 빠르게 확인하기만 하려면 루프백 주소용 로그인 없는 Demo를 사용할 수 있습니다.

SKYDOT_DEMO_OPEN=true PROVIDER_SETUP_SKIPPED=true npm start

공개 네트워크나 신뢰할 수 없는 네트워크에서는 Demo 모드를 활성화하지 마세요. 이 모드의 전체 제한 사항은 저장소의 DEMO.md를 참고하세요.

모델 Provider 구성

SkyDot에서는 먼저 인터페이스 초기화를 완료한 다음 설정에서 Provider를 추가할 수 있습니다. 실제 모델을 연결하려면 해당 API Key, Session Cookie 또는 기타 자격 증명을 준비해야 하며, 자격 증명을 스크린샷, 명령줄 기록 또는 Git 저장소에 기록하지 않도록 주의해야 합니다.

타사 OpenAI Completions 인터페이스를 사용하는 경우 Provider의 사용자 지정 환경 변수에 다음을 설정할 수 있습니다.

SKYDOT_MODEL_API=openai-completions

기본 프로토콜은 anthropic-messages이며, 이 설정은 일반 Dot 대화의 Host와 Container Runner에 함께 사용됩니다.

Agent 실행 모드 선택

Host 모드

Host 모드는 로컬 Runner를 직접 사용하므로 Docker가 필요하지 않으며, 로컬 개발과 빠른 검증에 적합합니다. 실행 권한은 여전히 Workspace, 사용자 및 실행 정책의 제한을 받습니다.

Container 모드

Container 모드를 사용하려면 Docker를 사용할 수 있어야 하며 Agent Runner 이미지를 준비해야 합니다. 기본 이미지는 2sincejuly/skydot-agent:latest이며, 현재 소스에서 빌드할 수도 있습니다.

docker build --pull -t 2sincejuly/skydot-agent:latest container

다른 이미지를 사용하려면 SKYDOT_CONTAINER_IMAGE를 설정할 수 있으며, 호환 설정 항목은 CONTAINER_IMAGE입니다. 서비스와 이미지 빌드는 동일한 Docker daemon에 연결되어야 합니다. make start 또는 make dev는 로컬 이미지를 우선 사용하고, 없으면 가져오기를 시도합니다.

데스크톱 Electron 실행

Backend와 Vite가 이미 시작된 경우 다른 터미널에서 Electron을 실행할 수 있습니다.

SKYDOT_RENDERER_URL=http://127.0.0.1:5173 npm run desktop:dev

Backend에서 빌드된 페이지를 이미 제공하는 경우 다음 명령을 직접 실행할 수도 있습니다.

npm run desktop:dev

Electron은 원격 Backend에도 연결할 수 있습니다.

SKYDOT_SERVER_URL=https://your-skydot.example.com npm run desktop:dev

로컬 패키징에는 다음 명령을 사용할 수 있습니다.

npm run desktop:package:dir
npm run desktop:package

프로젝트는 기본적으로 macOS arm64 패키징 구성을 제공하며 Windows와 Linux 대상도 유지합니다. 정식 출시 전에 대상 플랫폼에 맞게 서명과 공증을 구성해야 합니다.

주요 환경 변수

WEB_PORT: Backend 수신 포트이며 기본값은 3000입니다.
SKYDOT_SERVER_URL: Electron이 연결하는 Backend 주소이며 기본값은 http://127.0.0.1:3000입니다.
SKYDOT_RENDERER_URL: Electron이 로드하는 Renderer 주소입니다.
SKYDOT_CONTAINER_IMAGE: Agent Runner 컨테이너 이미지입니다.
PROVIDER_SETUP_SKIPPED: 시스템 설정 파일이 없을 때 Provider 안내를 건너뜁니다.
SKYDOT_BOT_GROUPS: 기본 멀티 Dot 그룹 채팅을 활성화합니다.
SKYDOT_BOT_HANDOFFS: 그룹 채팅에서 Bot 협업 실행을 활성화합니다.
SKYDOT_PERSONAL_GOALS: 개인 Goal 실험 기능을 활성화합니다.

개인 Goal과 Durable Runtime은 기본적으로 비활성화되어 있습니다. 일반 예약 작업은 이러한 스위치에 의존하지 않습니다. 구체적인 실행 전제 조건은 Goals and Tasks 문서를 확인하세요.

기본 사용 흐름

SkyDot에 로그인하고 관리자 초기화를 완료합니다.
설정에서 사용 가능한 Model Provider를 구성합니다.
Dot을 만들고 이름, Prompt, 모델 및 실행 정책을 설정합니다.
Dot에 Workspace를 지정하고 파일 및 메모리 경계가 예상대로 설정되었는지 확인합니다.
대화에서 작업을 보내고 스트리밍 출력, 도구 권한 부여 및 실행 결과를 확인합니다.
장기 실행이 필요하면 Cron, 고정 간격 또는 일회성 작업을 생성합니다.
여러 역할의 협업이 필요하면 그룹 채팅 기능을 활성화하고 Bot 협업 권한을 명확하게 구성합니다.

예를 들어 코드 분석을 담당하는 Dot과 자료 정리를 담당하는 Dot을 만들고, 이들을 같은 그룹 채팅에 추가할 수 있습니다. 사용자는 명확한 멘션이나 제어된 위임을 통해 작업을 할당하고, 공유 타임라인에서 진행 상황과 결과를 확인하면서 각 Workspace의 권한 경계를 유지할 수 있습니다.

운영 및 보안 권장 사항

런타임 데이터는 기본적으로 저장소의 data/ 디렉터리에 저장되며, 여기에는 SQLite, Workspace, Session, Memory와 실행 구성이 포함됩니다. 이 디렉터리는 Git에 포함되지 않지만 백업에 민감한 구성과 데이터베이스가 포함될 수 있으므로 원본 데이터와 동일한 수준으로 보호해야 합니다.

make status를 사용해 Backend, 로그 및 Docker 상태를 확인합니다.
make stop을 사용해 현재 포트에서 실행 중인 SkyDot 서비스를 중지합니다.
make backup을 사용해 런타임 데이터 백업을 생성합니다.
make restore FILE=...을 사용해 지정한 백업을 복원합니다.
make typecheck을 사용해 Backend, Web, Agent Runner 및 문서 검사를 실행합니다.
npm test -- --run을 사용해 Vitest 테스트를 실행합니다.

원격 배포 시에는 HTTPS와 WSS를 사용하고, 리버스 프록시, Cookie 및 접근 제어를 올바르게 구성해야 합니다. Renderer, 데이터베이스 또는 Docker daemon을 신뢰할 수 없는 사용자에게 직접 노출하지 말고, 편의를 위해 공개 Demo를 활성화하지도 마세요.

추가 확장

SkyDot의 기능 라이브러리는 내장, 호스트 시스템, 프로젝트, 사용자, Workspace 및 Plugin 등의 출처를 지원합니다. Agent가 실행되기 전에 사용 가능한 기능 목록을 생성하고, 정책에 따라 Prompt, 리소스 및 컨텍스트를 주입합니다. 또한 Plugin 버전 스냅샷, Subagents, 그리고 Host와 Container에 일관된 기능 경계를 지원합니다.

메시지 진입점 측면에서는 Web, PWA 및 Electron이 동일한 비즈니스 프런트엔드를 공유하며, Feishu, Telegram, QQ, DingTalk, WeChat, Discord, WhatsApp 등의 채널에 연결할 수 있습니다. 채널은 지정된 Workspace 또는 Session에 연결할 수 있습니다.

요약

SkyDot은 여러 Dot의 대화, Workspace 격리, Agent 실행, 예약 작업, 확장 기능 및 팀 권한을 하나의 자체 호스팅 워크벤치로 통합합니다. 이 문서에 따라 Node.js 환경을 준비하고, 의존성을 설치하고, 빌드 및 실행과 Provider 구성을 완료하면 먼저 개인 Dot을 실행한 뒤 Docker, Electron, 그룹 채팅, Scheduler, Skills, MCP 및 Memory 등의 기능을 단계적으로 활성화할 수 있습니다.

프로젝트는 아직 계속 개발 중이므로 실제 모델, Docker, 외부 채널 및 원격 배포에는 각각 해당 자격 증명과 실행 환경이 필요합니다. Goal, Durable 또는 Cloud Runtime과 같은 실험적 기능도 기본적으로 활성화된 기능으로 간주해서는 안 됩니다.