에이전트 대시보드

AI 코딩 에이전트가 자신이 무엇을 하고 있는지 보고하고, 사용자가 실시간으로 지켜보고 조종할 수 있는 자체 호스팅 대시보드입니다.

에이전트는 MCP(원격 Streamable HTTP — 로컬 설치 불필요)를 통해 연결하여 프로젝트를 만들고, 이미지와 비디오가 포함된 상태 업데이트를 게시하고, 작업을 요청하고, 사용자의 답변을 읽고, 사용자의 승인을 기다리며 차단합니다. 사용자는 브라우저에서 새로고침 없이 업데이트되는 라이브 피드를 봅니다.

상태: 개발 중. 설계는 완료되어 커밋되었으며, 구현은 이슈에서 추적됩니다.

기능

• 풍부한 상태 업데이트 — 에이전트가 작업하면서 게시하는 마크다운, 이미지, 비디오.

• 프로젝트 — 에이전트가 생성하며, 사용자는 이름 변경, 고정, 보관할 수 있습니다.

• 라이브 — 모든 것이 SSE를 통해 열린 브라우저로 스트리밍되며, 폴링이나 새로고침이 없습니다.

• 프레즌스 — 현재 살아있는 에이전트를 확인할 수 있습니다.

• 제어 평면 — 에이전트에게 작업을 할당하고, 답변하고, 사용자가 클릭하는 승인 뒤에 작업을 게이트합니다.

Related MCP server: Project Manager MCP

범위

단일 소유자 및 자체 호스팅. 하나의 배포, 하나의 소유자, 멀티 테넌시나 사용자 계정 없음. 한 대의 머신에서 수십 개의 에이전트와 수천 개 이하의 업데이트를 처리할 수 있는 규모.

설계

전체 아키텍처, 데이터 모델, MCP 도구 표면 및 승인 게이트 의미론은 docs/superpowers/specs/2026-08-25-agent-dashboard-design.md를 참조하세요.

개발

Node 22+ 및 PATH에 ffmpeg가 필요합니다.

npm ci
cp .env.example .env   # then fill in the secrets
npm run dev

컴포넌트 및 e2e 테스트는 첫 실행 시 Chromium 빌드를 다운로드하므로, CI와 기본 npm test는 의도적으로 노드 전용 단위 스위트만 사용합니다.

레이아웃

src/는 설계의 §2 모듈 테이블을 미러링합니다. 각 디렉토리에는 자신의 단일 역할과 가져올 수 있는 유일한 모듈을 명시한 README가 있습니다.

src/db/       SQLite connection, migrations, repositories
src/events/   typed in-process pub/sub + SSE ring buffer
src/media/    upload tokens, ingest, derivatives, disk layout
src/domain/   all business rules
src/mcp/      MCP Streamable HTTP tool surface
src/http/     SvelteKit routes (browser REST, SSE, /mcp mount, media, auth)
src/web/      Svelte components and client stores

SvelteKit은 라우트에 대해 src/http/routes를, $lib에 대해 src/web을 가리키므로 프레임워크의 자체 디렉토리가 모듈 경계와 일치하게 됩니다. $db, $events, $media, $domain, $mcp, $http 및 $web 별칭을 통해 모듈 간에 가져옵니다.

구성

모든 설정은 환경 변수입니다. 전체 목록과 기본값 및 각 비밀번호 생성 방법은 .env.example을 참조하세요. src/config.ts는 부팅 시 이를 검증하므로 잘못된 값은 첫 요청이 아니라 해당 변수 이름과 함께 실패합니다.

DATA_DIR을 백업하세요: SQLite 데이터베이스와 media/의 rsync. 설계의 sqlite3 .backup 지침은 sqlite3 CLI가 필요한데, 이는 이 앱이 사용하는 better-sqlite3 라이브러리와 별개의 패키지입니다 — 패키징 슬라이스는 이를 Docker 이미지에 포함하거나, better-sqlite3 자체의 db.backup()을 통해 온라인 백업을 수행해야 합니다.

배포

앱은 단일 Node 프로세스입니다. npm run build 후 node build를 실행하며, PORT(기본값 8010)에서 수신합니다.

TLS를 위해 리버스 프록시를 앞에 두세요. 그 프록시에 관한 두 가지는 선택 사항이 아닙니다.

라이브 피드는 버퍼링되지 않아야 합니다

대시보드는 /api/stream에서 Server-Sent Events로 스트리밍합니다. 버퍼링 프록시는 가장 혼란스러운 방식으로 이를 깨뜨립니다: 페이지가 연결되고, 오류를 보고하지 않으며, 단순히 업데이트되지 않습니다. Caddy는 text/event-stream을 자체적으로 감지하지만, 나중에 구성 변경이 회귀하지 않도록 명시적으로 말하세요.

agents.wildware.dev {
	@stream path /api/stream
	reverse_proxy @stream 127.0.0.1:8010 {
		flush_interval -1
	}

	# Wide enough for slow video uploads and the 55s approval-gate holds.
	reverse_proxy 127.0.0.1:8010 {
		transport http {
			read_timeout 300s
		}
	}
}

nginx 뒤에서는 해당 라우트에 proxy_buffering off와 proxy_read_timeout 300s가 동일합니다:

location /api/stream {
	proxy_pass http://127.0.0.1:8010;
	proxy_buffering off;
	proxy_cache off;
	proxy_read_timeout 300s;
	proxy_set_header Connection '';
	proxy_http_version 1.1;
}

클라이언트 주소가 전달되어야 합니다

ADDRESS_HEADER=X-Forwarded-For 및 XFF_DEPTH=1을 설정하세요 (.env.example 참조). 이 설정이 없으면 Node 어댑터는 모든 요청의 클라이언트로 프록시를 보고하므로 로그인 속도 제한기가 하나의 공유 버킷으로 축소되고, 낯선 사람의 5번의 잘못된 추측으로 소유자가 15분 동안 잠길 수 있습니다. 앱은 이 상태에서 시작을 거부하여 잠길 수 있는 대시보드를 제공하지 않습니다.

또한 PUBLIC_BASE_URL을 외부에서 접근 가능한 오리진으로 설정하세요. create_upload는 에이전트에게 이를 기반으로 한 절대 업로드 URL을 제공하며, 127.0.0.1 URL을 받은 에이전트는 아무것도 업로드할 수 없습니다.

백업

유지해야 할 두 가지: SQLite 파일과 data/media/. 프로세스가 쓰는 동안 파일을 복사하는 대신 SQLite의 온라인 백업을 통해 데이터베이스 사본을 가져오세요 — WAL 모드에서는 일반 cp가 찢어진 상태를 포착할 수 있습니다. sqlite3 CLI는 필요하지 않으며 설치되어 있다고 가정하지 않습니다.

라이선스

MIT