AgenticSeek: 프라이빗하고 로컬에서 실행되는 Manus 대안.

Manus AI에 대한 100% 로컬 대안으로, 음성 지원이 가능한 이 AI 어시스턴트는 모든 데이터를 사용자의 기기에 유지하면서 자율적으로 웹을 탐색하고, 코드를 작성하며, 작업을 계획합니다. 로컬 추론 모델 (local reasoning models)에 맞춤화되어 사용자의 하드웨어에서 완전히 실행되므로, 완전한 프라이버시를 보장하고 클라우드 의존성이 전혀 없습니다.

왜 AgenticSeek 인가요?

🔒 완전한 로컬 및 프라이빗 (Fully Local & Private) - 모든 것이 사용자의 기기에서 실행됩니다 — 클라우드도, 데이터 공유도 없습니다. 사용자의 파일, 대화, 검색 기록은 프라이빗하게 유지됩니다.
🌐 스마트 웹 브라우징 (Smart Web Browsing) - AgenticSeek은 스스로 인터넷을 탐색할 수 있습니다 — 검색, 읽기, 정보 추출, 웹 양식 채우기 — 이 모든 것이 핸즈프리로 이루어집니다.
💻 자율 코딩 어시스턴트 (Autonomous Coding Assistant) - 코드가 필요하신가요? 감독 없이도 Python, C, Go, Java 등에서 프로그램을 작성, 디버깅 및 실행할 수 있습니다.
🧠 스마트 에이전트 선택 (Smart Agent Selection) - 사용자가 질문하면, 작업에 가장 적합한 에이전트를 자동으로 파악합니다. 마치 도움을 줄 준비가 된 전문가 팀을 보유한 것과 같습니다.
📋 복잡한 작업 계획 및 실행 (Plans & Executes Complex Tasks) - 여행 계획부터 복잡한 프로젝트까지 — 큰 작업을 단계별로 나누고 여러 AI 에이전트를 사용하여 일을 완수할 수 있습니다.
🎙️ 음성 지원 (Voice-Enabled) - 깔끔하고 빠르며 미래지향적인 음성 및 음성-텍스트 변환 (speech to text) 기능을 통해 마치 공상 과학 영화 속 개인 AI와 대화하듯 말할 수 있습니다. (진행 중)

데모 (Demo)

agenticSeek 프로젝트를 검색해서 어떤 기술이 필요한지 알아낸 다음, CV_candidates.zip 파일을 열어서 어떤 것이 프로젝트와 가장 잘 맞는지 나에게 말해줄 수 있어?

면책 조항 (Disclaimer): 나타나는 모든 파일(예: CV_candidates.zip)을 포함한 이 데모는 전적으로 허구입니다. 저희는 기업이 아니며, 채용 후보자가 아닌 오픈 소스 (Open-source) 기여자를 찾고 있습니다.

🙏 이 프로젝트는 사이드 프로젝트 (Side-project)로 시작되었으며, 로드맵 (Roadmap)도 없고 자금 지원 (Funding)도 전혀 없습니다. GitHub Trending에 오르며 제가 예상했던 것보다 훨씬 더 크게 성장했습니다. 기여, 피드백, 그리고 인내에 깊은 감사를 드립니다.

사전 요구 사항 (Prerequisites)

시작하기 전에 다음 소프트웨어가 설치되어 있는지 확인하십시오:

Git: 저장소 (Repository)를 클론 (Clone)하기 위해 필요합니다. Git 다운로드
Python 3.10.x: Python 3.10.x 버전을 사용할 것을 강력히 권장합니다. 다른 버전을 사용하면 의존성 (Dependency) 오류가 발생할 수 있습니다. Python 3.10 다운로드 (3.10.x 버전을 선택하세요).
Docker Engine & Docker Compose: SearxNG와 같은 번들링된 서비스를 실행하기 위해 필요합니다.
- Docker Desktop (Docker Compose V2 포함) 설치: Windows | Mac | Linux
- 또는 Linux에서 Docker Engine과 Docker Compose를 별도로 설치: Docker Engine | Docker Compose (Compose V2를 설치해야 합니다. 예: sudo apt-get install docker-compose-plugin).

1. 저장소 클론 및 설정

git clone https://github.com/Fosowl/agenticSeek.git
cd agenticSeek
mv .env.example .env

2. .env 파일 내용 변경

SEARXNG_BASE_URL="http://searxng:8080" # 호스트에서 실행하는 경우 http://127.0.0.1:8080
REDIS_BASE_URL="redis://redis:6379/0"
WORK_DIR="/Users/mlg/Documents/workspace_for_ai"
...

필요에 따라 .env 파일을 본인의 값으로 업데이트하십시오:

SEARXNG_BASE_URL: CLI 모드로 호스트에서 실행하는 경우가 아니라면 변경하지 마십시오.
REDIS_BASE_URL: 변경하지 마십시오.
WORK_DIR: 로컬 머신의 작업 디렉토리 경로입니다. AgenticSeek은 이 파일들을 읽고 상호작용할 수 있습니다.
OLLAMA_PORT: Ollama 서비스의 포트 번호입니다.
LM_STUDIO_PORT: LM Studio 서비스의 포트 번호입니다.
CUSTOM_ADDITIONAL_LLM_PORT: 추가적인 커스텀 LLM 서비스를 위한 포트입니다.

LLM을 로컬에서 실행하기로 선택한 사용자에게 API 키는 완전히 선택 사항입니다. 이것이 이 프로젝트의 주요 목적입니다. 충분한 하드웨어를 갖추고 있다면 비워 두십시오.

3. Docker 시작하기

시스템에 Docker가 설치되어 있고 실행 중인지 확인하십시오. 다음 명령어를 사용하여 Docker를 시작할 수 있습니다:

Linux/macOS의 경우:
터미널을 열고 다음을 실행하십시오:
```
sudo systemctl start docker
```
또는 설치되어 있다면 애플리케이션 메뉴에서 Docker Desktop을 실행하십시오.
Windows의 경우:
시작 메뉴에서 Docker Desktop을 시작하십시오.

다음 명령어를 실행하여 Docker가 실행 중인지 확인할 수 있습니다:

docker info

Docker 설치에 대한 정보가 나타나면 정상적으로 실행되고 있는 것입니다.

요약 정보는 아래의 로컬 프로바이더 표를 참조하십시오.

다음 단계: AgenticSeek 로컬에서 실행하기

문제가 발생하면 문제 해결 (Troubleshooting) 섹션을 참조하십시오.
하드웨어가 LLM을 로컬에서 실행할 수 없는 경우, API로 실행하기 위한 설정 (Setup to run with an API)을 참조하십시오.
config.ini에 대한 자세한 설명은 설정 섹션 (Config Section)을 참조하십시오.

로컬 머신에서 LLM을 실행하기 위한 설정

하드웨어 요구 사항:

LLM을 로컬에서 실행하려면 충분한 하드웨어가 필요합니다. 최소한 Magistral, Qwen 또는 Deepseek 14B를 실행할 수 있는 GPU가 필요합니다. 모델/성능에 대한 자세한 권장 사항은 FAQ를 참조하십시오.

로컬 프로바이더 설정

로컬 프로바이더를 시작하십시오 (예: ollama 사용):

AgenticSeek를 호스트에서 실행(CLI 모드)하려는 것이 아니라면, 프로바이더(provider)의 리슨 주소(listen address)를 내보내거나 설정하십시오:

export OLLAMA_HOST=0.0.0.0:11434

그 다음, 프로바이더를 시작하십시오:

ollama serve

지원되는 로컬 프로바이더 목록은 아래를 참조하십시오.

config.ini 업데이트

config.ini 파일을 수정하여 provider_name을 지원되는 프로바이더로 설정하고, provider_model을 해당 프로바이더가 지원하는 LLM (Large Language Model)으로 설정하십시오. Mistral 또는 Deepseek와 같은 추론 모델 (reasoning model)을 권장합니다.

필요한 하드웨어 사양은 README 끝에 있는 FAQ를 참조하십시오.

[MAIN]
is_local = True # 로컬에서 실행하거나 원격 프로바이더를 사용하는 경우 모두 해당합니다.
provider_name = ollama # 또는 lm-studio, openai 등..
...

주의 사항:

config.ini 파일 형식은 주석 (comments)을 지원하지 않습니다. 예시 설정 내용을 그대로 복사하여 붙여넣지 마십시오. 주석이 있으면 오류가 발생할 수 있습니다. 대신, 주석을 제외하고 원하는 설정값으로 config.ini 파일을 수동으로 수정하십시오.
LLM을 실행하기 위해 LM-studio를 사용하는 경우, provider_name을 openai로 설정하지 마십시오. lm-studio로 설정해야 합니다.
일부 프로바이더 (예: lm-studio)는 IP 앞에 http://를 붙여야 합니다. 예: http://127.0.0.1:1234

로컬 프로바이더 목록

프로바이더 (Provider)	로컬 지원 여부	설명
ollama	예	ollama를 LLM 프로바이더로 사용하여 로컬에서 쉽게 LLM 실행
...

다음 단계: 서비스 시작 및 AgenticSeek 실행

문제가 발생하면 문제 해결 (Troubleshooting) 섹션을 참조하십시오.
하드웨어가 로컬에서 LLM을 실행할 수 없는 경우, API를 사용하여 실행하는 설정을 참조하십시오.
config.ini에 대한 자세한 설명은 설정 섹션 (Config Section)을 참조하십시오.

API를 사용하여 실행하는 설정

이 설정은 외부 클라우드 기반 LLM 프로바이더를 사용합니다. 선택한 서비스의 API 키가 필요합니다.

1. API 프로바이더를 선택하고 API 키를 발급받으십시오:

아래의 API 프로바이더 목록을 참조하십시오. 해당 웹사이트를 방문하여 가입하고 API 키를 발급받으십시오.

2. API 키를 환경 변수 (Environment Variable)로 설정하십시오:

Linux/macOS:
터미널을 열고 export 명령어를 사용하십시오. 설정이 유지되도록 셸(shell)의 프로필 파일(예: ~/.bashrc, ~/.zshrc)에 추가하는 것이 가장 좋습니다.
```
export PROVIDER_API_KEY="your_api_key_here"
# PROVIDER_API_KEY를 구체적인 변수명으로 바꾸십시오. 예: OPENAI_API_KEY, GOOGLE_API_KEY
```
TogetherAI의 예시:
```
export TOGETHER_API_KEY="xxxxxxxxxxxxxxxxxxxxxx"
```
Windows:
- 명령 프롬프트 (Command Prompt, 현재 세션에만 임시 적용):
```
set PROVIDER_API_KEY=your_api_key_here
```
- PowerShell (현재 세션에만 임시 적용):
```
$env:PROVIDER_API_KEY="your_api_key_here"
```
- 영구 설정: Windows 검색창에 "환경 변수"를 검색하고, "시스템 환경 변수 편집"을 클릭한 다음 "환경 변수(" 버튼을 클릭하십시오. 적절한 이름(예: OPENAI_API_KEY)과 키를 값으로 하는 새 사용자 변수를 추가하십시오.
(자세한 내용은 FAQ: API 키를 어떻게 설정하나요?를 참조하십시오).

3. config.ini 업데이트:

[MAIN]
is_local = False
provider_name = openai # 또는 google, deepseek, togetherAI, huggingface
...

주의: config.ini 값의 끝에 공백이 포함되지 않도록 주의하십시오.

API 프로바이더 목록

Provider	`provider_name`	Local?	Description	API Key Link (Examples)
OpenAI	`openai`	No	OpenAI의 API를 통해 ChatGPT 모델을 사용합니다.	platform.openai.com/signup
...

참고:

현재 프롬프트 최적화(Prompt optimizations)가 Deepseek과 같은 모델에 맞춰져 있으므로, 복잡한 웹 브라우징 및 작업 계획(Task planning)을 위해 gpt-4o 또는 기타 OpenAI 모델을 사용하는 것은 권장하지 않습니다.
코딩/bash 작업의 경우, Gemini가 Deepseek에 최적화된 포맷팅 프롬프트(Formatting prompts)를 엄격하게 따르지 않을 수 있어 문제가 발생할 수 있습니다.
is_local = False인 경우, API 엔드포인트(Endpoint)가 일반적으로 각 프로바이더의 라이브러리에 하드코딩되어 있으므로 config.ini의 provider_server_address는 대개 사용되지 않습니다.

다음 단계: 서비스 시작 및 AgenticSeek 실행

문제가 발생할 경우 Known issues (알려진 문제) 섹션을 참조하십시오.

상세한 설정 파일 설명은 Config (설정) 섹션을 참조하십시오.

서비스 시작 및 실행

기본적으로 AgenticSeek은 Docker 환경에서 완전히 실행됩니다.

옵션 1: Docker에서 실행하고 웹 인터페이스(Web interface) 사용:

필요한 서비스들을 시작합니다. 이는 다음을 포함하여 docker-compose.yml의 모든 서비스를 시작합니다:
- searxng
- redis (searxng에 필요함)
- frontend (프론트엔드)
- backend (백엔드) (웹 인터페이스 사용 시 full 옵션 사용 시)

./start_services.sh full # MacOS
start start_services.cmd full # Windows

경고: 이 단계에서는 모든 Docker 이미지(Docker images)를 다운로드하고 로드하며, 최대 30분이 소요될 수 있습니다. 서비스를 시작한 후, 메시지를 보내기 전에 백엔드 서비스가 완전히 실행될 때까지 기다려 주십시오 (로그에서 backend: "GET /health HTTP/1.1" 200 OK가 보여야 합니다). 백엔드 서비스는 첫 실행 시 시작하는 데 최대 5분이 걸릴 수 있습니다.

http://localhost:3000/로 이동하면 웹 인터페이스를 볼 수 있습니다.

서비스 시작 문제 해결: 만약 이 스크립트들이 실패한다면, Docker Engine이 실행 중인지 그리고 Docker Compose (V2, docker compose)가 올바르게 설치되었는지 확인하십시오. 터미널의 출력 결과에서 에러 메시지를 확인하십시오. FAQ: 도움말! AgenticSeek 또는 관련 스크립트를 실행할 때 에러가 발생합니다.를 참조하십시오.

옵션 2: CLI 모드:

CLI 인터페이스로 실행하려면 호스트에 패키지를 설치해야 합니다:

./install.sh
./install.bat # windows

그 다음 config.ini 파일 내의 SEARXNG_BASE_URL을 다음과 같이 변경해야 합니다:

SEARXNG_BASE_URL="http://localhost:8080"

필요한 서비스들을 시작하십시오. 이 과정은 다음을 포함하여 docker-compose.yml의 일부 서비스들을 시작합니다:
- searxng
- redis (searxng에 의해 필요함)
- frontend

./start_services.sh # MacOS
start start_services.cmd # Window

실행: uv가 pip를 활성화할 수 있도록 uv run: uv run python -m ensurepip를 실행하십시오.

CLI 사용: uv run cli.py

사용법 (Usage)

./start_services.sh full을 통해 서비스들이 정상적으로 가동 중인지 확인한 후, 웹 인터페이스를 위해 localhost:3000으로 이동하십시오.

설정에서 listen = True로 설정하면 음성 인식(Speech to Text)을 사용할 수도 있습니다. 이는 CLI 모드에서만 가능합니다.

종료하려면 단순히 goodbye라고 말하거나 입력하십시오.

다음은 몇 가지 사용 예시입니다:

python으로 스네이크 게임을 만들어줘!

Show HN: AgenticSeek – 클라우드 기반 AI 도구의 셀프 호스팅 대안

요약

핵심 포인트