n8n 자동화를 위한 오픈 소스 명령 센터입니다. 여러 인스턴스를 관리하고, 오류를 모니터링하며, 노드별로 실행 과정을 추적하고, AI 도움을 받아 워크플로우 코드를 작성하며, 지식 소스를 연결하는 모든 작업을 하나의 대시보드에서 처리할 수 있습니다.
클라이언트나 여러 팀을 위해 n8n을 운영한다는 것은 여러 로그인 정보와 흩어진 로그를 다루고, 무엇이 문제인지 통합적인 그림을 그리기 어렵다는 것을 의미합니다. AgeniusDesk CE는 이러한 모든 인스턴스를 한곳에 모아주는 가벼운 제어 평면(control plane)입니다.
n8n 중심 설계. 대시보드, 오류 피드, OpenTelemetry 추적 기록, Code Lab, 인사이트 등 모든 것이 n8n 워크플로우를 중심으로 돌아갑니다. 또한 선택 사항인 에이전트 계층(LangGraph / PydanticAI 에이전트를 직접 구축하고 실행할 수 있음)도 있지만, 기본적으로는 비활성화되어 있습니다. 따라서 기본 설치는 집중된 n8n 제어 평면이며, 추가로 학습하거나 실행할 것은 없습니다. 원한다면 활성화하세요 (Agent Fleet 참고).
대시보드 둘러보기 (전체 품질 비디오).
스틸 이미지를 선호하시나요? 아래에 몇 가지 하이라이트를 제공합니다.
| 개요 | 노드별 관찰: 추적 기록 보기 |
|---|
| |
| |
| 에이전트 플릿 (선택 사항) | 예정된 백업 + 오프사이트 |
| |
| |
다중 인스턴스 관리
- URL과 API 키를 사용하여 모든 수의 n8n 인스턴스를 추가할 수 있습니다.
- 인스턴스 간 즉시 전환이 가능합니다.
- 모든 워크플로우, 최근 실행 기록, 오류 이력을 한 곳에서 볼 수 있습니다.
- 플릿 상태(Fleet Health): 연결된 모든 인스턴스의 워크플로우 상태와 오류를 하나의 창에 통합하여 보여줍니다 (인스턴스별 활성/총 워크플로우 수, 최근 실행을 기준으로 한 오류율, 비정상적인 워크플로우 및 전체 합계). 성능이 저하되었거나 연결할 수 없는 인스턴스는 표시되지만 치명적이지는 않습니다.
오류 가시성(Error Visibility)
- 모든 인스턴스를 아우르는 실시간 오류 피드입니다.
- 워크플로우, 노드, 오류 유형별로 그룹화되어 발생 횟수와 함께 표시됩니다.
- 전체 노드 수준의 세부 정보와 마지막 확인 시각이 제공됩니다.
- '사일런트 실패(Silent failure)'도 자체 오류가 발생하는 것처럼 동일한 피드에 기록됩니다.
class: runs n8n이 성공으로 보고되지만, Continue-On-Fail 설정 하에서 노드에 오류가 발생했거나 데이터를 조용히 생성하지 않아 '녹색이지만 손상된(green but broken)' 실행 기록이 표시되는 경우, 사용자가 이미 분류할 수 있습니다. Silent-failure detection을 참조하세요.
워크플로우 승격 (Workflow Promotion) (dev에서 staging으로, staging에서 prod로)
- 워크플로우를 한 등록 인스턴스에서 다른 인스턴스로 이동시키는 기능으로, n8n Enterprise 환경에 대한 오픈 소스 솔루션입니다.
- **사전 점검(preflight)**이 먼저 실행되어 워크플로우가 바인딩하는 모든 자격 증명(credential)을 보고하고, 대상 시스템이 해당 자격 증명 유형을 이미 가지고 있는지 여부와 이름 충돌 같은 중복 문제를 알려줍니다. 따라서 어떤 것도 쓰기 전에 무엇이 깨질지 알 수 있습니다.
- **자격 증명 자동 프로비저닝 (Credential auto-provision)**은 대상에 이미 미러링된 자격 증명을 재사용하거나, Secrets 스토어의 일치하는 항목에서 새 자격 증명을 생성합니다. 모호성은 절대 추측되지 않습니다: 여러 개의 미러가 있는 유형은 사용자가 해결하도록 표시되며, 프로비저닝은 재사용을 통해멱등적(idempotent)이므로, 이미 승격된 워크플로우의 자격 증명 ID가 갑자기 사라지는 일이 없습니다.
- **활성화 (Activation)**는 보호됩니다. n8n은 노드 자격 증명을 ID와 이름 모두로 바인딩하므로, 매핑된 자격 증명이 대상에 이름을 가지고 있지 않은 경우 실행 시점에 조용히 실패하는 대신 거부(refused)되며, 이 거부는 n8n 자체의 노드별 설명을 표시합니다. Workflow Promotion을 참조하세요.
코드 랩 (Code Lab)
- n8n Code-node 로직 작성을 위한 Monaco 기반 에디터입니다.
- 구문 강조(Syntax highlighting), 자동 완성, n8n 노드 인트로스펙션 기능이 제공됩니다.
- 코드를 생성하거나 설명하는 AI 지원 기능을 이용할 수 있습니다.
- 한 번의 클릭으로 'n8n에 전송(Send to n8n)'하여 바로 배포할 수 있습니다.
Agent Builder: AI 지원을 받아 LangGraph 또는 PydanticAI 에이전트(ReAct, human-in-the-loop, 병렬 팬아웃 스타터)를 구축한 다음 Agent Fleet에 등록합니다.
Agent Fleet (선택 사항이며 기본적으로 비활성화되어 있습니다)
- AgeniusDesk가 n8n을 운영하는 방식처럼 작동하는 관리형 에이전트 플릿: 카탈로그, 실시간 그래프 + 정규화된 실행 워터폴, 인간 개입 루프(human-in-the-loop) 승인/재개, 그리고 호출별 토큰/비용 추적을 위한 LangSmith 트레이싱 - 즉시 사용 가능한 내장 기능 (ops-triage, fix-proposer, health-reporter);
Code Lab에서 직접 구축하고 등록: LangGraph 또는 PydanticAI를 사용하여 자신만의 에이전트를 만들고 등록할 수 있습니다. - 사용자의 에이전트는 agents/ 아래의 볼트 내 파일이며, 사용자가 소유하고 편집하며 내보낼 수 있고, 재시작 없이 실시간으로 발견됩니다. - LangGraph/PydanticAI 스택은 선택적 종속성 확장 기능이므로, AgeniusDesk는 기본적으로 n8n 전용입니다. 에이전트 플릿과 에이전트 빌더는 사용자가 옵트인 할 때까지 숨겨져 있습니다. 다음 명령어로 에이전트를 활성화하세요: AGD_EXTRAS="assistant,langgraph"
(또는 pip install '.[langgraph]')
.AGD_AGENTS_ENABLED은 자동 감지(false)를 덮어씁니다. (false로 설정하면 확장 기능이 있어도 n8n 전용을 유지하고; true로 설정하면 강제로 활성화합니다.)
AI 어시스턴트 (AI Assistant)
- 워크플로우 및 오류 기록의 컨텍스트와 대화합니다.
- OpenRouter(하나의 키로 수백 개의 모델), OpenAI, Anthropic, Perplexity, Groq, DeepSeek, Mistral, xAI(Grok), Together AI, 로컬 Ollama 또는 사용자 정의 기본 URL을 통해 모든 OpenAI 호환 엔드포인트(Azure OpenAI, LiteLLM, vLLM, LocalAI 등)와 작동합니다. 각 영역(Code Lab / 오류 트리아지 / 어시스턴트)은 자체 제공업체 및 모델을 선택합니다.
- 워크플로우 쿼리, 실행 실행, 오류 보기 등을 위한 함수 호출
행동하기 전에 질문합니다. 이 어시스턴트는 사용자가 통제할 수 없는 콘텐츠(n8n 오류 및 실행 페이로드, RAG 히트, MCP 서버 출력)를 읽기 때문에, 그 안에 숨겨진 프롬프트 인젝션은 상태 변경 도구 호출을 유도할 수 있습니다. 이러한 호출은 채팅 턴 내부에서 실행되지 않습니다. 대신 승인 카드에 제안으로 돌아오며, 사용자가 확인하기 전까지는 아무 일도 일어나지 않습니다. MCP 도구는 서버 자체의 readOnlyHint 주석별로 분류되며, 분류할 수 없는 도구는 안전하게 비활성화(fails closed)됩니다. AGD_ASSISTANT_AUTORUN을 설정하세요.
원격 접속 환경(headless install)에서 비감시적 실행을 복구하려면 - MCP 서버를 연결하여 어시스턴트를 외부 도구로 확장하세요
n8n 인텔리전스가 설치됩니다. 최초 부팅 시 AgeniusDesk는 czlonkowski가 만든 n8n-mcp(심층적인 n8n 노드 지식과 워크플로우 검색, 검증 및 생성/업데이트 도구 포함)를 실행 중인 MCP 서버로 자동 설치하고, 사용자의 작업 공간에 선별된 n8n 스킬 라이브러리를 주입하여 Code Lab과 어시스턴트가 처음부터 워크플로우를 올바르게 구축할 수 있도록 합니다. 이 기능들은 모두 최선의 노력(best-effort)이며 선택적입니다 (AGD_N8N_MCP_AUTO=false, AGD_SEED_SKILLS=false). n8n-mcp 카드는 설정(Settings) > MCP 서버에 있습니다.
지식 기반 (Knowledge Management)
- 외부 지식 소스 등록 (마크다운 파일, API, 문서)
- 전체 텍스트 검색 및 백링크가 가능한 마크다운 노트 작성 및 정리
- Obsidian과 호환되는 폴더 트리 구조
- 태그 기반의 구성 및 탐색
컨테이너 관리 (Container Management)
- 대시보드에서 Docker 컨테이너 목록 확인, 검사 및 관리
- 원클릭 템플릿을 사용하여 새 서비스 배포
- n8n 템플릿은 두 개의 컨테이너 번들(n8n + 작업 실행기 사이드카)로 배포되어 Python 코드 노드가 바로 작동하며, 표준 라이브러리가 기본적으로 열려 있습니다. - 커뮤니티 템플릿 라이브러리 (JSON 파일을
data/templates/에 드롭)
- 워크플로우 가져오기, 내보내기 및 백업
비밀 저장소 (Secrets Store)
- Fernet 암호화 자격 증명 저장소
- 인스턴스 API 키와 MCP 서버 구성에서
$VAR_NAME으로 비밀 참조 - 해석 순서: 환경 변수 우선, 그 다음 암호화된 저장소
알림 (Notifications)
- 대시보드 메시지를 토스트로 표시하는 수신 웹훅
- 선택적 Slack 및 Discord 통합 (SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL)
- 코드에 API 키가 내장되어 있지 않음
통찰력 (Insights)
- 실행 분석: 성공률, 오류 추세, 가장 바쁜 워크플로우
- 인스턴스별 상태 확인
관측 가능성 (Observability) (OpenTelemetry)
- 임베디드 OTLP/HTTP 수신기: n8n의 네이티브 OpenTelemetry exporter를 AgeniusDesk에 연결하여 외부 collector가 필요하지 않습니다.
- Observe 뷰: 실시간 트레이스 목록과 부모/자식 실행 워터폴, 그리고 메트릭 스트립(실행 횟수, 오류율, p50/p95, 처리량)을 제공합니다.
- LLM 비용 추적을 트레이스 레이어에 통합: 토큰 사용량 및 계층형 가격 책정표를 기반으로 개별 트레이스 및 호출당 지출액을 파악할 수 있습니다.
- 오류(Errors) 및 인사이트(Insights)에서 실행별 트레이스 링크 제공
- 무음 실패 감지(Silent-failure detection): n8n이 성공으로 보고했지만 실제로는 문제가 있는 '녹색이지만 고장난' 실행을 플래그합니다 (예: Continue-On-Fail 하에서 오류가 발생한 노드, 또는 정상적인 볼륨보다 조용히 아무것도 반환하지 않거나 크게 감소한 안정적인 프로듀서). 이는 다운스트림 캐스케이드가 아닌 원본 노드를 플래그하며, 토스트 알림, Observe의 실행별 '무음' 배지, Errors 피드의 자체
Silent failure 클래스, 그리고 Overview 및 Insights의 카운트로 모든 곳에서 확인할 수 있습니다. 작동 방식과 왜 n8n 자체 상태로는 이를 포착할 수 없는지에 대한 내용은 Silent-failure detection에 작성되어 있습니다.
n8n에 OpenTelemetry 활성화하기
관측 가능성(Observability) 및 무음 실패 감지 기능은 n8n이 트레이스를 내보내기 시작해야만 작동합니다. AgeniusDesk가 **제공하는 인스턴스는 자동 연결(auto-wired)**됩니다 (별도로 할 일이 없습니다). 하지만 URL로 연결하는 기존 인스턴스의 경우, 사용자가 직접 n8n의 네이티브 OpenTelemetry export를 활성화해야 하며, 그렇지 않으면 Observe 뷰와 무음 실패 감지 기능은 비어 있게 됩니다. 이 설정들을 n8n 인스턴스의 환경 변수에 지정하고 재시작하세요 (n8n은 엔드포인트에 /v1/traces를 추가합니다):
N8N_OTEL_ENABLED=true
N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<dashboard-host>:<port>/api/otel
N8N_OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer <AGD_OTEL_TOKEN>
수신기 측에서도 AgeniusDesk에 AGD_OTEL_ENABLED=true (그리고 이상적으로는 AGD_OTEL_TOKEN)가 필요합니다. CONFIG.md를 참조하세요.
커뮤니티 모듈
- GitHub 리포지토리에서 두 단계의 검사 및 설치 플로우를 통해 타사 모듈을 설치합니다.
- 정적 코드 스캔은 각 모듈이 선언한 기능(네트워크 호스트, 파일 시스템 쓰기 경로, 서브프로세스)을 파악하고, 사용자가 동의하기 전에 위험한 호출을 표시합니다.
- 비례적 동의(Proportional consent), 설치별 감사 추적(audit trail), 그리고 활성화를 위한 원클릭 재시작 기능이 제공됩니다.
- 선택적인 프로세스 외부 격리(out-of-process isolation) (옵트인, Settings > Modules): 모듈의 백엔드를 샌드박스 서브프로세스 또는 자체 강화된 Docker 컨테이너(읽기 전용 rootfs, 모든 Linux 기능 제거, Docker 소켓 없음, 호스트 시크릿 없음)에서 실행할 수 있습니다. 특권적 작업은 루프백 기능 브리지를 통해 이루어집니다: 모듈이 선언한 경로로 제한된 볼트 접근 권한과, 제공업체 키가 모듈에 절대 도달하지 않도록 호스트 측에서 실행되는 도구 없는 LLM 호출이 포함됩니다. 기본값은 프로세스 내(in-process)입니다 - 첫 번째 모듈: YouTube Research (링크를 붙여넣으면 구조화된 분석 결과를 노트 볼트에 자동 저장), 이는 프로세스 내 또는 격리된 환경에서 동일한 코드를 실행합니다.
- 기본 프로세스 내 모드는 샌드박스가 아닌 휴리스틱 검토(heuristic review)입니다. 신뢰하는 출처에서만 프로세스 내 모듈을 설치하십시오. 실제 경계를 원한다면 컨테이너 단계를 활성화하세요.
테마 및 음악 (Themes and Music)
- 3가지 기본 테마(Dark, Light, n8n)와 사용자 정의 테마 지원
- 통합 음악 플레이어 (Spotify, YouTube, SoundCloud, Apple Music, Tidal)
AI 비서와 함께 설정하시겠습니까? AI-SETUP-PROMPT.md를 제공하세요.
git clone https://github.com/Mfrostbutter/ageniusdesk-ce.git
cd ageniusdesk-ce
cp .env.example .env
...
http://localhost:3000에서 열면 설정 마법사가 첫 번째 n8n 인스턴스를 추가하는 과정을 안내합니다.
포트 3000이 이미 사용 중인가요? 이는 일반적인 개발 포트이므로, 이미 다른 것을 실행하고 있다면(종종 이전의 AgeniusDesk) 충돌할 가능성이 높습니다. .env 파일이나 인라인으로 PORT을 지정하여 사용 가능한 호스트 포트를 선택하세요:
PORT=8080 docker compose up -d --build # 그런 다음 http://localhost:8080에서 열기
컨테이너는 항상 내부적으로 3000번 포트에서 수신하며, PORT은 호스트 포트만 변경합니다. 만약 docker compose up을 실행하면...
printsBind for 0.0.0.0:3000 failed: port is already allocated
, 즉 충돌(collision)이 발생한 것이니 PORT를 사용 가능한 포트로 설정하고 다시 실행하세요.
Agents는 선택 사항입니다. 위의 설치 방법은 n8n 전용입니다. Agent Fleet과 Code Lab의 Agent Builder가 나타나도록 에이전트 스택으로 빌드하려면, 다음을 추가한 후 빌드하세요:
git clone https://github.com/Mfrostbutter/ageniusdesk-ce.git
cd ageniusdesk-ce
cp .env.example .env
...
Surface는 이 에이전트를 자동으로 감지합니다 (추가 플래그 필요 없음). 내장된 에이전트는 Claude에서 실행되므로, Anthropic 키를 설정하세요: .env 파일에서 ANTHROPIC_KEY= 주석을 해제하거나, 첫 부팅 후 Settings → Secrets에서 추가할 수 있습니다. 에이전트가 설치되었더라도 n8n 전용 경험으로 강제하려면 AGD_AGENTS_ENABLED=false로 설정하세요.
Python 3.10 이상 필요.
git clone https://github.com/Mfrostbutter/ageniusdesk-ce.git
cd ageniusdesk-ce
pip install '.[assistant]'
...
자신의 도메인으로 HTTPS를 통해 모든 장치에서 AgeniusDesk에 접속하고 싶으신가요? 배포 가이드에는 공개 VPS(DigitalOcean, Hostinger 등)를 위한 단계별 안내가 있습니다: 서버 프로비저닝, 도메인 연결, Docker로 AgeniusDesk 실행, 그리고 자동 HTTPS를 위해 Caddy로 프론팅하는 방법과 강화 체크리스트까지 포함되어 있습니다. docs/DEPLOY.md를 참조하세요.
설정은 환경 변수와 .env 파일을 통해 제어됩니다. 전체 참고 자료는 docs/CONFIG.md에 있습니다.
주요 변수:
PORT
- 대시보드 포트 (기본값 3000)
SECRET_KEY