접수 데스크
브라우저에서 열리는 첫 화면입니다. 채팅, 스킬 실행, 기억 파일 편집, 일정 등록, 백업 생성의 출발점입니다.
GitHub repo manual
Agentic OS를 처음 쓰는 사람을 위한 운영 매뉴얼
Agentic OS는 여러 AI 에이전트를 한 화면에서 실행하고, 기억 파일, 스킬, 스케줄러, 비용 기록, 백업을 함께 관리하는 로컬 대시보드입니다. 이 문서는 초보자가 설치부터 첫 작업까지 안전하게 따라 할 수 있도록 구성했습니다.
Overview
이 저장소가 하는 일
Agentic OS는 AI 모델 자체가 아니라, 이미 설치된 에이전트 CLI들을 묶어서 관리하는 개인용 관제판입니다. 코딩은 opencode, 기억과 일정은 Hermes, 조사와 분석은 Gemini CLI처럼 역할을 나누고, 결과를 대시보드에서 확인하게 합니다.
1. 초보자 설명AI 에이전트 OS가 무엇인지 쉽게 이해합니다.
2. 구조도대시보드, API, 에이전트, 파일 저장소의 관계를 봅니다.
3. 설치와 실행clone, install.sh, start.sh 순서로 실행합니다.
4. 화면별 사용법Chat, Skills, Memory, Scheduler, Backups를 익힙니다.
5. Interactive flow상태 확인부터 백업까지 클릭하며 흐름을 익힙니다.
6. 에이전트 선택어떤 요청을 어느 에이전트에게 맡길지 정합니다.
7. 운영 체크백업, 비용, 감사 로그, 설정 변경 기준을 확인합니다.
8. 문제 해결처음 막히기 쉬운 지점을 빠르게 점검합니다.
Beginner first
초보자를 위한 쉬운 설명: Agentic OS는 “AI 직원 접수 데스크”입니다
Agentic OS를 처음 볼 때 가장 헷갈리는 지점은 “이게 AI 모델인가, 앱인가, 자동화 도구인가?”입니다. 답은 조금 다릅니다. Agentic OS는 AI 모델 하나가 아니라, 여러 AI 도구를 한 화면에서 부르고 기록하는 로컬 관제 대시보드입니다.
한 줄 요약
“직접 일하는 AI 모델”이 아니라,
“여러 AI 직원에게 일을 배정하는 접수 데스크”입니다.
사용자는 브라우저 대시보드에 요청을 넣고, Agentic OS는 요청 종류에 따라 opencode, Hermes, Gemini CLI 같은 외부 에이전트 도구를 호출합니다. 그래서 먼저 봐야 할 것은 “모델 성능”이 아니라 어떤 작업을 어떤 직원에게 맡기는 구조인지입니다.
용어
Agentic OS (에이전틱 운영체제)
여기서 OS는 macOS나 Windows처럼 컴퓨터 전체를 제어한다는 뜻이 아닙니다. 여러 AI 도구를 한 화면에서 연결하고, 기억 파일과 스케줄을 함께 관리한다는 의미에 가깝습니다.
사무실 비유
회사에 접수 데스크가 있고, 그 뒤에 개발 담당, 기억 담당, 조사 담당 직원이 있다고 생각하면 쉽습니다. 접수 데스크는 일을 직접 끝내지 않습니다. 대신 “이 일은 개발 담당에게”, “이 일은 조사 담당에게”처럼 맞는 사람에게 넘기고 기록을 남기는 곳입니다.
업무 매뉴얼 카드
코드 리뷰, 데일리 스탠드업, 백업처럼 반복 업무를 정해진 순서대로 실행하게 만든 작업 묶음입니다.
직원들이 읽는 업무 노트
brain/ 폴더의 Markdown 파일입니다. 프로젝트 맥락, 최근 결정, 제약 조건을 다음 작업의 기준으로 씁니다.
초보자 함정
대시보드가 열리면 모든 AI가 준비됐다고 착각하기
Agentic OS 대시보드는 Python 서버만으로도 열릴 수 있습니다. 하지만 opencode, Hermes, Gemini CLI가 설치되어 있지 않거나 로그인/API 키가 없으면 일부 기능은 offline 또는 warning 상태가 됩니다.
좋은 시작법
먼저 “상태 확인”을 작업 1번으로 둡니다
처음에는 복잡한 자동화보다 Dashboard와 Setup Wizard에서 Agent Status를 확인하세요. 대시보드가 열리는 것과 에이전트가 실제로 일을 처리할 준비가 된 것은 서로 다른 상태입니다.
Mental model
Agentic OS 구조도
사용자가 브라우저에서 버튼을 누르면 정적 SPA가 FastAPI 서버의 REST API를 호출합니다. 서버는 로컬 파일을 읽고 쓰거나, 필요한 경우 외부 에이전트 CLI를 실행합니다.
Install
설치와 첫 실행
기본 대시보드는 Python만 있어도 실행할 수 있지만, 에이전트별 기능을 제대로 쓰려면 Node.js, opencode, Hermes Agent, Gemini CLI 설정을 차례로 확인해야 합니다.
1
저장소 받기
GitHub에서 코드를 내려받고 폴더로 이동합니다.
2
설치 실행
`install.sh`가 Python 패키지를 설치하고 필수 폴더를 만듭니다.
3
에이전트 설정
opencode, Hermes, Gemini CLI 중 사용할 도구를 설치하거나 로그인합니다.
4
대시보드 시작
`start.sh`가 `server.py`를 실행합니다. 기본 포트는 8080입니다.
5
상태 확인
브라우저에서 Agent Status와 Setup Wizard를 확인합니다.
터미널에서 실행하는 기본 명령
git clone https://github.com/modimihir07/agentic-os.git
cd agentic-os
chmod +x install.sh
./install.sh
./start.sh
# 브라우저에서 열기
http://127.0.0.1:8080| 준비 항목 | 왜 필요한가 | 초보자 체크 |
|---|---|---|
| Python 3.10+ | FastAPI 서버와 스케줄러 실행 | `python3 --version`이 3.10 이상인지 확인합니다. |
| Node.js 18+ | opencode와 Gemini CLI 같은 Node 기반 CLI 설치 | `node --version`이 v18 이상이면 안전합니다. |
| opencode | 코드 생성, 파일 작업, DevOps 요청 담당 | 없어도 대시보드는 열리지만 code/devops 작업은 실패할 수 있습니다. |
| Hermes Agent | 기억, 일정, 메시징 성격의 작업 담당 | OpenRouter 키는 `~/.hermes/.env`에서 읽습니다. |
| Gemini CLI | 웹 조사, 분석, 멀티모달 작업 담당 | `gemini auth login`으로 OAuth 로그인을 완료합니다. |
Dashboard
화면별 사용법
왼쪽 사이드바의 각 메뉴는 `dashboard/pages/*.js` 모듈로 구현되어 있습니다. 처음에는 Dashboard, Setup Wizard, AI Chat, Skills, Memory, Scheduler 순서로 보면 이해가 쉽습니다.
| 화면 | 무엇을 하는 곳인가 | 처음 해볼 일 |
|---|---|---|
| Dashboard | 에이전트 상태, 스킬 개수, 최근 활동을 요약해서 봅니다. | Agent Status가 online, warning, offline 중 무엇인지 확인합니다. |
| Setup Wizard | 시작 전 준비 상태를 단계별로 확인합니다. | 각 에이전트 상태를 보고 빠진 CLI나 로그인 항목을 찾습니다. |
| AI Chat | opencode, Hermes, Gemini 중 하나를 골라 메시지를 보냅니다. | `System Check`, `Recall Memory`, `Research` 빠른 프롬프트를 눌러 차이를 봅니다. |
| Skills Hub | 스킬 목록, 설명, learnings, eval 정보를 보고 실행합니다. | `heartbeat` 또는 `daily-standup`처럼 낮은 위험의 스킬부터 실행합니다. |
| Memory | `brain/` 안의 업무 노트를 읽고 수정합니다. | `active-projects.md`, `recent-decisions.md`를 열어 현재 맥락을 확인합니다. |
| Scheduler | 스킬을 cron 형식으로 예약합니다. | 기본 등록된 heartbeat, memory consolidation, daily standup 작업을 확인합니다. |
| Audit | 스킬 실행, 설정 변경, 백업 같은 활동 기록을 확인합니다. | 스킬을 하나 실행한 뒤 audit entry가 생겼는지 봅니다. |
| Backups | brain, skills, agents, registry, standards, prompts를 tar.gz로 백업합니다. | 큰 수정 전 `New Backup`을 눌러 스냅샷을 만듭니다. |
First workflow
처음 사용하는 날의 interactive flow
아래 단계 제목을 눌러 보면서 흐름을 익히세요. 처음에는 복잡한 자동화 작업을 예약하지 말고, 상태 확인 → 기억 확인 → 낮은 위험의 스킬 실행 → 기록 확인 → 백업 생성 순서로 시스템이 실제로 연결되어 있는지 봅니다.
Dashboard에서 Agent Status 확인
Memory에서 업무 노트 확인
Skills Hub에서 낮은 위험 스킬 실행
Audit와 learnings 확인
Backups에서 스냅샷 생성
1단계: Dashboard에서 “일할 준비가 됐는지” 봅니다
Dashboard는 출근부처럼 봅니다. 대시보드가 켜졌다는 사실보다 중요한 것은 opencode, Hermes, Gemini가 online, warning, offline 중 어떤 상태인지입니다.
- 볼 것: Agent Status, skills_count, recent activity
- 성공 신호: 최소 한 에이전트가 online 또는 warning으로 표시됩니다.
- 주의: All agents offline이면 먼저 CLI 설치와 로그인을 확인합니다.
Dashboard에서 Agent Status 확인
Memory에서 업무 노트 확인
Skills Hub에서 낮은 위험 스킬 실행
Audit와 learnings 확인
Backups에서 스냅샷 생성
2단계: Memory에서 에이전트가 읽을 배경지식을 확인합니다
brain/ 폴더는 에이전트용 업무 노트입니다. 사람이 잘못된 업무 지시서를 보고 일하면 결과가 틀리듯,
에이전트도 오래된 프로젝트 맥락을 읽으면 엉뚱한 답을 낼 수 있습니다.
- 볼 것:
active-projects.md,recent-decisions.md,constraints.md - 성공 신호: 현재 프로젝트, 최근 결정, 하지 말아야 할 일이 최신입니다.
- 주의: API 키나 비밀번호를 memory 파일에 적지 않습니다.
Dashboard에서 Agent Status 확인
Memory에서 업무 노트 확인
Skills Hub에서 낮은 위험 스킬 실행
Audit와 learnings 확인
Backups에서 스냅샷 생성
3단계: Skills Hub에서 작은 작업부터 실행합니다
처음부터 배포나 파일 대량 수정 같은 작업을 시키지 마세요. heartbeat, daily-standup,
goal-planner처럼 결과를 읽고 되돌리기 쉬운 스킬로 연결 상태를 확인합니다.
- 볼 것: 스킬 설명, Primary agent, Run 결과
- 성공 신호: run_id와 agent 이름이 결과에 표시됩니다.
- 주의: auto 라우팅이 이상하면 agent를 직접 골라 다시 실행합니다.
Dashboard에서 Agent Status 확인
Memory에서 업무 노트 확인
Skills Hub에서 낮은 위험 스킬 실행
Audit와 learnings 확인
Backups에서 스냅샷 생성
4단계: 실행 기록이 남았는지 확인합니다
Agentic OS의 장점은 실행 후 흔적을 남기는 것입니다. Audit은 누가 무엇을 실행했는지 보는 활동 기록이고,
learnings.md는 각 스킬이 실행되며 배운 내용을 누적하는 파일입니다.
- 볼 것: Audit Log의 action, skill, agent, timestamp
- 성공 신호: 방금 실행한 스킬의 기록이 최근 항목에 있습니다.
- 주의: 기록이 없다면 서버 API 호출이 실패했거나 다른 인스턴스를 보고 있을 수 있습니다.
Dashboard에서 Agent Status 확인
Memory에서 업무 노트 확인
Skills Hub에서 낮은 위험 스킬 실행
Audit와 learnings 확인
Backups에서 스냅샷 생성
5단계: 첫 정상 상태를 백업합니다
한 번 연결이 확인되면 Backups에서 스냅샷을 만듭니다. 백업은 brain/, skills/,
agents/, registry/, standards/, prompts/를 묶습니다.
- 볼 것: 백업 파일명, 생성 시간, 파일 크기
- 성공 신호:
agentic-os-YYYYMMDD_HHMMSS.tar.gz형식의 파일이 생깁니다. - 주의: Restore는 현재 파일을 덮어쓸 수 있으니 복원 전에도 백업을 만듭니다.
성공 기준
대시보드가 열리고, 최소 한 에이전트가 online 또는 warning으로 표시되며, 낮은 위험의 스킬 실행 후 Audit에 기록이 남으면 1차 연결은 된 것입니다.
Agent routing
어떤 에이전트에게 맡길까
저장소의 `data/agent-routes.json`은 요청 키워드에 따라 기본 담당 에이전트를 나눕니다. 초보자는 아래 기준으로 먼저 선택하면 됩니다.
코드와 시스템 작업
코드 생성, 파일 작업, Git, 배포, 테스트, 디버깅, 인프라 점검처럼 실제 개발 작업에 적합합니다.
기억과 일정 작업
최근 작업 회상, 기억 정리, 스케줄, 알림, 채널 연동처럼 지속적인 맥락 관리에 적합합니다.
조사와 분석 작업
웹 조사, 비교, 요약, 문서 이해, 멀티모달 분석처럼 자료를 읽고 정리하는 작업에 적합합니다.
Operations
운영할 때 지켜야 할 기준
Agentic OS는 로컬 파일을 실제로 수정하고 백업을 만들 수 있습니다. 초보자는 설정 변경과 복구 작업을 하기 전에 아래 체크리스트를 확인하세요.
변경 전 체크리스트
- 현재 포트와 접속 주소가 맞는지 확인했습니다.
- `brain/` 파일의 프로젝트 맥락이 최신입니다.
- 위험한 작업 전 Backups에서 새 백업을 만들었습니다.
- API 키나 OAuth 토큰을 공개 저장소에 넣지 않았습니다.
작업 후 체크리스트
- Audit에서 작업 기록을 확인했습니다.
- 스킬 실행 결과가 기대한 에이전트로 처리됐는지 봤습니다.
- Settings 변경 후 대시보드를 새로고침했습니다.
- Cost Analytics에 예상치 못한 비용 기록이 없는지 확인했습니다.
Troubleshooting
처음 막히는 지점
대부분의 문제는 대시보드 문제와 에이전트 CLI 준비 문제를 구분하면 빨리 해결됩니다.
서버와 포트를 확인합니다
`./start.sh` 출력에 표시된 주소를 그대로 엽니다. `data/settings.json`에 포트가 있으면 8080이 아닐 수 있습니다.
CLI 설치 여부를 봅니다
`which opencode`, `which hermes`, `which gemini`로 실제 명령이 잡히는지 확인합니다.
OAuth 토큰을 확인합니다
서버는 `~/.gemini/oauth_creds.json`에 유효한 토큰이 있는지 확인합니다. `gemini auth login`을 다시 실행합니다.
담당 에이전트를 바꿔 봅니다
스킬 실행 모달에서 agent를 auto 대신 opencode, hermes, gemini 중 하나로 명시해 원인을 좁힙니다.
Restore는 덮어쓰기입니다
복원은 tar.gz 내용을 프로젝트 폴더에 풀어 현재 파일을 바꿀 수 있습니다. 실행 전 현재 상태도 백업하세요.
자동 과금 추적은 제한적입니다
`/api/cost/record`와 Cost 화면은 기록 파일 기반입니다. 실제 제공자 청구액과 항상 자동 동기화된다고 보면 안 됩니다.
Comic recap
지식 만화로 한 번 더 이해하기
Agentic OS의 핵심 흐름을 4컷으로 다시 정리합니다.
1
🧑💻❓
문제
AI 도구가 흩어져 있습니다
코딩, 기억, 조사 도구가 따로 있으면 어디에 무엇을 맡길지 헷갈립니다.
“이건 누구에게 시키지?”
2
🖥️📬
발견
대시보드가 접수합니다
Agentic OS는 한 화면에서 요청을 받고 적절한 에이전트로 넘깁니다.
“먼저 접수 데스크로!”
3
⚙️🧠🔎
작동
일은 역할별로 나뉩니다
코드는 opencode, 기억과 일정은 Hermes, 조사는 Gemini CLI가 맡습니다.
“각자 잘하는 일이 달라요.”
4
✅💾
검토
기록과 백업을 남깁니다
Audit, learnings, backups를 확인해야 다음 작업을 안전하게 이어갈 수 있습니다.
“끝나면 흔적을 확인!”
시도해볼 만한 것
처음 10분은 “자동화”가 아니라 “연결 확인”에 씁니다
- Dashboard를 먼저 봅니다. 에이전트 상태가 모두 offline이면 설치와 로그인을 먼저 해결합니다.
- Memory를 읽습니다. 오래된 프로젝트 맥락이 있으면 에이전트 작업도 틀어질 수 있습니다.
- 낮은 위험 스킬을 실행합니다. heartbeat나 daily-standup으로 실행 경로를 확인합니다.
- Audit와 Backup을 확인합니다. 기록과 복구 지점이 있어야 다음 작업을 안전하게 키울 수 있습니다.
확인한 출처와 파일
- GitHub: modimihir07/agentic-os
- `README.md` — 제품 설명, 기능, 설치, 구조, 에이전트 역할
- `install.sh`, `start.sh`, `requirements.txt` — 설치와 실행 경로
- `server.py` — FastAPI API, 에이전트 상태 확인, 스킬 실행, 백업, 설정, 채팅
- `dashboard/index.html`, `dashboard/app.js`, `dashboard/pages/*.js` — 실제 대시보드 메뉴와 화면 동작
- `data/agent-routes.json`, `scheduler/jobs/*.json`, `skills/*/SKILL.md`, `registry/plugins.json` — 라우팅, 예약 작업, 스킬 목록, 플러그인 구조
기준 저장소 커밋은 `8468035`입니다. 이 매뉴얼은 해당 시점의 공개 저장소 파일을 바탕으로 작성했으며, 실제 외부 CLI 로그인 상태나 사용자의 로컬 API 키는 포함하지 않습니다.