# Installazione manuale

> Distribuisci PentAGI manualmente con Docker Compose: crea la directory di lavoro, compila il file .env, aggiungi un provider LLM e avvia lo stack.

Usa la procedura manuale quando vuoi il controllo completo sulla configurazione o non puoi eseguire il programma di installazione interattivo.

## [1. Crea una directory di lavoro](https://pentagi.com/it/docs/getting-started/manual-installation/#1-create-a-working-directory)

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

## [2. Scarica il file di ambiente](https://pentagi.com/it/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
```

Il file compose monta tre file di configurazione dei [provider](https://pentagi.com/it/docs/glossary/#provider), quindi creali — vanno bene anche file vuoti:

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

Se intendi usare un endpoint personalizzato compatibile con OpenAI oppure Ollama, recupera le configurazioni di esempio anziché i file vuoti e imposta `LLM_SERVER_CONFIG_PATH` o `OLLAMA_SERVER_CONFIG_PATH` in `.env` su `/opt/pentagi/conf/custom.provider.yml` o `/opt/pentagi/conf/ollama.provider.yml`. L'esempio personalizzato cita modelli OpenAI, tra cui `o3-mini`, che OpenAI dismetterà il 23 ottobre 2026: imposta il `model` di ogni [agent type](https://pentagi.com/it/docs/glossary/#agent-type) su uno fornito dal tuo endpoint:

```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. Aggiungi almeno un LLM provider](https://pentagi.com/it/docs/getting-started/manual-installation/#3-add-at-least-one-llm-provider)

Modifica `.env` e imposta la chiave di almeno un provider:

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

Altri providers — AWS Bedrock, Ollama, DeepSeek, GLM, Kimi, Qwen, MiniMax, Mistral, xAI ed endpoint personalizzati — sono descritti in [LLM providers](https://pentagi.com/it/docs/configuration/llm-providers/). I [search engines](https://pentagi.com/it/docs/glossary/#search-engine) sono opzionali; DuckDuckGo e Sploitus non richiedono alcuna chiave:

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

## [4. Avvia lo stack](https://pentagi.com/it/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
```

L'interfaccia web è disponibile all'indirizzo `https://localhost:8443`. Accedi con `admin@pentagi.com` / `admin` e cambia la password.

L'interfaccia web e gli altri servizi sono vincolati a localhost, ma il [sandbox](https://pentagi.com/it/docs/glossary/#sandbox) di ogni [flow](https://pentagi.com/it/docs/glossary/#flow) pubblica due porte di callback, da `28000` a `29999` per impostazione predefinita, su tutte le interfacce dell'host Docker e ufw non le filtra. Su un host raggiungibile da altri, limita prima quell'intervallo — vedi [Esposizione alla rete](https://pentagi.com/it/docs/configuration/security/#network-exposure). Per aggiornare l'installazione in seguito, segui [Aggiornamento](https://pentagi.com/it/docs/deployment/upgrade/).

## [Stack opzionali](https://pentagi.com/it/docs/getting-started/manual-installation/#optional-stacks)

Ogni servizio opzionale è definito in un file compose separato da combinare con quello base:

| Stack                                              | File compose                                                                                       | Cosa aggiunge                                         |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Osservabilità LLM                                  | [`docker-compose-langfuse.yml`](https://pentagi.com/it/docs/configuration/observability/#langfuse)                       | Langfuse con ClickHouse, Redis e MinIO                |
| [Knowledge graph](https://pentagi.com/it/docs/glossary/#knowledge-graph) | [`docker-compose-graphiti.yml`](https://pentagi.com/it/docs/concepts/memory/#knowledge-graph-optional)                   | Graphiti e Neo4j                                      |
| Osservabilità di sistema                           | [`docker-compose-observability.yml`](https://pentagi.com/it/docs/configuration/observability/#grafana-and-opentelemetry) | Grafana, OpenTelemetry, VictoriaMetrics, Jaeger, Loki |

> [!WARNING]
> In produzione e in qualsiasi ambiente in cui viene eseguito codice non attendibile, isola i container dei [tool](https://pentagi.com/it/docs/glossary/#tool) su un [worker node](https://pentagi.com/it/docs/deployment/worker-node/) dedicato.