# 수동 설치

> Docker Compose를 사용하여 PentAGI를 수동으로 배포합니다. 작업 디렉터리를 생성하고, .env 파일을 채우고, LLM provider를 추가한 후 스택을 시작하세요.

구성을 완전히 제어하고 싶거나 대화형 설치 프로그램을 실행할 수 없는 경우 수동 설치 방식을 사용하세요.

## [1. 작업 디렉터리 생성](https://pentagi.com/ko/docs/getting-started/manual-installation/#1-create-a-working-directory)

```bash
mkdir -p ~/pentagi && cd ~/pentagi
```

## [2. 환경 파일 다운로드](https://pentagi.com/ko/docs/getting-started/manual-installation/#2-download-the-environment-file)

```bash
test -f .env || curl -fo .env.new https://raw.githubusercontent.com/vxcontrol/pentagi/main/.env.example
test -f .env.new && openssl rand -hex 32 | xargs -I VALUE sed -E -i.bak 's/^COOKIE_SIGNING_SALT=salt( .*)?$/COOKIE_SIGNING_SALT=VALUE/' .env.new
test -f .env.new && openssl rand -hex 16 | xargs -I VALUE sed -E -i.bak 's/^PENTAGI_POSTGRES_PASSWORD=postgres( .*)?$/PENTAGI_POSTGRES_PASSWORD=VALUE/' .env.new
test -f .env || mv .env.new .env
```

Compose 파일에서 세 개의 [provider](https://pentagi.com/ko/docs/glossary/#provider) 설정 파일을 마운트하므로 해당 파일을 생성해 주세요. 빈 파일로 생성해도 됩니다:

```bash
touch example.custom.provider.yml example.ollama.provider.yml example.bedrock.provider.yml
```

사용자 지정 OpenAI 호환 엔드포인트나 Ollama를 사용할 계획이라면 빈 파일 대신 예제 설정을 다운로드한 후, `.env`의 `LLM_SERVER_CONFIG_PATH` 또는 `OLLAMA_SERVER_CONFIG_PATH`가 `/opt/pentagi/conf/custom.provider.yml` 또는 `/opt/pentagi/conf/ollama.provider.yml`를 가리키도록 설정해 주세요. 사용자 지정 예제는 `o3-mini` 등 OpenAI 모델을 명시하는데, OpenAI는 2026년 10월 23일에 이를 퇴역시킵니다. 각 [agent](https://pentagi.com/ko/docs/glossary/#agent)의 `model`를 해당 엔드포인트에서 제공하는 모델 중 하나로 설정하세요:

```bash
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/main/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/main/examples/configs/ollama-llama318b.provider.yml
```

## [3. 하나 이상의 LLM provider 추가](https://pentagi.com/ko/docs/getting-started/manual-installation/#3-add-at-least-one-llm-provider)

`.env`를 편집하여 하나 이상의 provider 키를 설정해 주세요:

```bash
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
```

AWS Bedrock, Ollama, DeepSeek, GLM, Kimi, Qwen, MiniMax, Mistral, xAI 및 사용자 지정 엔드포인트 등 다른 providers에 대한 설명은 [LLM providers](https://pentagi.com/ko/docs/configuration/llm-providers/) 문서를 참고하세요. [Search engines](https://pentagi.com/ko/docs/glossary/#search-engine)는 선택 사항이며 DuckDuckGo와 Sploitus는 키가 필요하지 않습니다:

```bash
DUCKDUCKGO_ENABLED=true
SPLOITUS_ENABLED=true
TAVILY_API_KEY=your_tavily_key
```

## [4. 스택 시작](https://pentagi.com/ko/docs/getting-started/manual-installation/#4-start-the-stack)

```bash
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose.yml
test -f .env && docker compose up -d
```

웹 UI는 `https://localhost:8443`에서 이용할 수 있습니다. `admin@pentagi.com` / `admin`으로 로그인한 후 비밀번호를 변경해 주세요.

웹 UI와 다른 서비스는 localhost에 바인딩되지만, 각 [flow](https://pentagi.com/ko/docs/glossary/#flow)의 [sandbox](https://pentagi.com/ko/docs/glossary/#sandbox)는 기본적으로 `28000`–`29999` 범위의 두 콜백 포트를 Docker 호스트의 모든 인터페이스에서 게시하며, ufw는 이를 필터링하지 않습니다. 다른 사용자가 접근할 수 있는 호스트에서는 먼저 해당 범위를 제한하십시오. [네트워크 노출](https://pentagi.com/ko/docs/configuration/security/#network-exposure)을 참조하십시오. 나중에 설치를 업데이트하려면 [업그레이드](https://pentagi.com/ko/docs/deployment/upgrade/)를 따르십시오.

## [선택적 스택](https://pentagi.com/ko/docs/getting-started/manual-installation/#optional-stacks)

각 선택적 서비스는 별도의 Compose 파일로 제공되며 기본 스택 위에 계층적으로 추가할 수 있습니다:

| 스택                                                 | Compose 파일                                                                                         | 추가 기능                                                 |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| LLM 관측성                                            | [`docker-compose-langfuse.yml`](https://pentagi.com/ko/docs/configuration/observability/#langfuse)                       | ClickHouse, Redis, MinIO를 포함한 Langfuse                |
| [Knowledge graph](https://pentagi.com/ko/docs/glossary/#knowledge-graph) | [`docker-compose-graphiti.yml`](https://pentagi.com/ko/docs/concepts/memory/#knowledge-graph-optional)                   | Graphiti 및 Neo4j                                      |
| 시스템 관측성                                            | [`docker-compose-observability.yml`](https://pentagi.com/ko/docs/configuration/observability/#grafana-and-opentelemetry) | Grafana, OpenTelemetry, VictoriaMetrics, Jaeger, Loki |

> [!WARNING]
> 운영 환경 및 신뢰할 수 없는 코드가 실행되는 모든 환경에서는 [tool](https://pentagi.com/ko/docs/glossary/#tool) 컨테이너를 전용 [worker node](https://pentagi.com/ko/docs/deployment/worker-node/)에 격리해야 합니다.