# Instalação manual

> Implante o PentAGI manualmente com Docker Compose — crie o diretório de trabalho, preencha o arquivo .env, adicione um provider de LLM e inicie a stack.

Use o caminho manual quando você quiser controle total sobre a configuração ou não puder executar o instalador interativo.

## [1. Crie um diretório de trabalho](https://pentagi.com/pt-br/docs/getting-started/manual-installation/#1-create-a-working-directory)

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

## [2. Baixe o arquivo de ambiente](https://pentagi.com/pt-br/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
```

O arquivo compose monta três arquivos de configuração de [provider](https://pentagi.com/pt-br/docs/glossary/#provider), então crie-os — arquivos vazios servem:

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

Se você planeja usar um endpoint customizado compatível com OpenAI ou o Ollama, baixe as configurações de exemplo em vez de usar arquivos vazios e aponte `LLM_SERVER_CONFIG_PATH` ou `OLLAMA_SERVER_CONFIG_PATH` no `.env` para `/opt/pentagi/conf/custom.provider.yml` ou `/opt/pentagi/conf/ollama.provider.yml`. O exemplo customizado nomeia modelos da OpenAI, entre eles `o3-mini`, que a OpenAI descontinuará em 23 de outubro de 2026 — defina o `model` de cada [agent type](https://pentagi.com/pt-br/docs/glossary/#agent-type) como um que seu endpoint sirva:

```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. Adicione pelo menos um LLM provider](https://pentagi.com/pt-br/docs/getting-started/manual-installation/#3-add-at-least-one-llm-provider)

Edite o `.env` e defina a chave de pelo menos um provider:

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

Outros providers — AWS Bedrock, Ollama, DeepSeek, GLM, Kimi, Qwen, MiniMax, Mistral, xAI e endpoints customizados — são descritos em [LLM providers](https://pentagi.com/pt-br/docs/configuration/llm-providers/). Os [search engines](https://pentagi.com/pt-br/docs/glossary/#search-engine) são opcionais; DuckDuckGo e Sploitus não precisam de chave:

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

## [4. Inicie a stack](https://pentagi.com/pt-br/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
```

A interface web é servida em `https://localhost:8443`. Faça login com `admin@pentagi.com` / `admin` e altere a senha.

A interface web e os outros serviços ficam restritos ao localhost, mas o [sandbox](https://pentagi.com/pt-br/docs/glossary/#sandbox) de cada [flow](https://pentagi.com/pt-br/docs/glossary/#flow) publica duas portas de callback, de `28000` a `29999` por padrão, em todas as interfaces do host Docker, e o ufw não as filtra. Em um host acessível por outras pessoas, restrinja primeiro esse intervalo — veja [Exposição de rede](https://pentagi.com/pt-br/docs/configuration/security/#network-exposure). Para atualizar a instalação posteriormente, siga [Atualização](https://pentagi.com/pt-br/docs/deployment/upgrade/).

## [Stacks opcionais](https://pentagi.com/pt-br/docs/getting-started/manual-installation/#optional-stacks)

Cada serviço opcional vem com seu próprio arquivo compose que você adiciona em camadas sobre o arquivo base:

| Stack                                              | Arquivo compose                                                                                    | O que adiciona                                        |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Observabilidade de LLM                             | [`docker-compose-langfuse.yml`](https://pentagi.com/pt-br/docs/configuration/observability/#langfuse)                       | Langfuse com ClickHouse, Redis e MinIO                |
| [Knowledge graph](https://pentagi.com/pt-br/docs/glossary/#knowledge-graph) | [`docker-compose-graphiti.yml`](https://pentagi.com/pt-br/docs/concepts/memory/#knowledge-graph-optional)                   | Graphiti e Neo4j                                      |
| Observabilidade do sistema                         | [`docker-compose-observability.yml`](https://pentagi.com/pt-br/docs/configuration/observability/#grafana-and-opentelemetry) | Grafana, OpenTelemetry, VictoriaMetrics, Jaeger, Loki |

> [!WARNING]
> Para produção e qualquer ambiente onde código não confiável seja executado, isole os containers de [tool](https://pentagi.com/pt-br/docs/glossary/#tool) em um [worker node](https://pentagi.com/pt-br/docs/deployment/worker-node/) dedicado.