> For the complete documentation index, see [llms.txt](https://docs.dropzone.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dropzone.ai/edge/readme/installation.md).

# Installation

{% hint style="warning" %}
GitBook, our documentation hosting solution, is currently experiencing an outage. We are tracking this via <https://status.gitbook.com> and with our support reps.

Until it is resolved this documentation may be out of date.
{% endhint %}

## Obtain the Dropzone Package

Installation requires a deployment package (`dropzone.tgz`). You should have already discussed a delivery method with our Customer Success team. Transfer the package to the target instance once received.

Along with the package, you will receive `dropzone.tgz.sha256` — a SHA256 digest that verifies the package has not been corrupted or tampered with. Your Dropzone support contact can verify this SHA256 with you out of band if you wish.

### Verify Package Integrity

After transferring both files to the target instance, verify the package checksum:

```bash
sha256sum -c dropzone.tgz.sha256
```

{% hint style="info" %}
This command can take a very long time, and will show no feedback until it's done reading the entire tarball.
{% endhint %}

You should see `dropzone.tgz: OK`. If the check fails, re-download the package and try again. Contact our Customer Success team if the issue persists.

## Extract and Run the Installer

1. Extract the installer from the deployment package

```bash
tar -xzf dropzone.tgz --occurrence=1 dropzone-ai/deploy-dropzone
```

{% hint style="info" %}
This command can take a very long time, and will show no feedback until it's done reading the entire tarball.
{% endhint %}

1. Run the installer

```bash
./dropzone-ai/deploy-dropzone install dropzone.tgz
```

This creates the following directory structure:

| Path                    | Purpose                       |
| ----------------------- | ----------------------------- |
| `/opt/dropzone/bin/`    | Deployment management scripts |
| `/opt/dropzone/deploy/` | Configuration files           |
| `/srv/dropzone/`        | Persistent application data   |

{% hint style="success" %}
The installer copies sample configuration files to `/opt/dropzone/deploy/`. You will customize these in the next steps.
{% endhint %}

## Configure `config.yml`

Edit `/opt/dropzone/deploy/config.yml` to match your environment. The file is organized into five sections described below.

### `apis` — API Keys and Credentials

Set the API key(s) for whichever AI providers you will use. At minimum, one AI provider API key is required.

| Key                         | Required                  | Description                                                                                                                                                                               |
| --------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai-region`                 | No                        | Geographic region for AI providers: `us` (default) or `eu`. Controls which regional endpoints are used across all providers. Can be overridden per-provider in `ai_provider_config.yaml`. |
| `openai-api-key`            | If using OpenAI           | Your OpenAI API key                                                                                                                                                                       |
| `openai-api-key-eu`         | If using OpenAI EU region | Your OpenAI EU-region API key                                                                                                                                                             |
| `azure-openai-api-key`      | If using Azure OpenAI     | Your Azure OpenAI API key                                                                                                                                                                 |
| `anthropic-api-key`         | If using Anthropic        | Your Anthropic API key                                                                                                                                                                    |
| `bedrock-api-key`           | If using Bedrock          | Your AWS Bedrock API key                                                                                                                                                                  |
| `gemini-api-key`            | If using Gemini           | Your Gemini API key                                                                                                                                                                       |
| `vertex-ai-credentials-b64` | Required if using Gemini  | Vertex AI credentials, base64-encoded                                                                                                                                                     |

{% hint style="info" %}
To generate `vertex-ai-credentials-b64`: create a GCP service account with the **Vertex AI User** and **Vertex AI Viewer** roles, then download its JSON key file. Base64-encode the file contents:

```bash
base64 -w 0 service-account-key.json
```

On macOS, you can encode directly from the clipboard if you copied the JSON:

```bash
pbpaste | base64 | pbcopy
```

The value must be valid JSON before encoding. Verify it parses correctly before encoding: `cat service-account-key.json | jq .`
{% endhint %}

Additional optional keys in this section support specific integrations:

| Key                                 | Required                  | Description                                                       |
| ----------------------------------- | ------------------------- | ----------------------------------------------------------------- |
| `google-workspace-credentials-json` | If using Google Workspace | Service account credentials JSON (quote and escape double quotes) |
| `perplexity-api-key`                | If using Perplexity       | Perplexity API key                                                |

{% hint style="info" %}
Keys not relevant to your deployment can be left empty or at their default values.
{% endhint %}

### `connector` — Connector Authentication

Generate connector secrets by running the provided script:

```bash
python3 dropzone-ai/generate_connector_secrets.py
```

Paste the resulting values into the three fields: `auth`, `fingerprint`, and `key`.

### `custom` — Deployment-Specific Settings

| Key                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hostname`           | Yes      | Fully qualified hostname for this deployment (e.g. `mycompany.example.net`)                                                                                                                                                                                                                                                                                                                    |
| `hostname-connector` | Yes      | Connector hostname, must resolve to the same IP (e.g. `mycompany-connector.example.net`)                                                                                                                                                                                                                                                                                                       |
| `tenant-name`        | Yes      | Tenant name for this deployment                                                                                                                                                                                                                                                                                                                                                                |
| `embedding-model`    | No       | The embedding model to use. Supported values: `text-embedding-3-large` (default), `text-embedding-3-small`, `text-embedding-ada-002`, `gemini-embedding-001`, `amazon.titan-embed-text-v2:0`. Must match a model available from your configured AI providers                                                                                                                                   |
| `features`           | Yes      | Comma-separated list of feature flags to enable. Must include `model_agnosticism_force_enabled` (required for AI provider/model configuration to work correctly on edge deployments). Also include `terrarium` to enable Response Actions (recommended). Set to `model_agnosticism_force_enabled,terrarium`. Our Customer Success team can advise on any additional values for your deployment |

{% hint style="warning" %}
The `hostname` and `tenant-name` values are used for product licensing. Do not change them without engaging our Customer Success team.
{% endhint %}

{% hint style="warning" %}
If you set `only_listed_models: true` for a provider in `ai_provider_config.yaml`, ensure the embedding model is also listed under that provider's `models:` section. If the embedding model is not listed, embedding operations will fail.
{% endhint %}

The remaining fields in this section have sensible defaults. Engage our Customer Success team before changing them.

### `local` — TLS, Databases, and Secrets

| Key                 | Required | Description                                                                                    |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `dhparam-pem`       | Yes      | DH parameters in PEM format (a default is provided — you may leave as-is or generate your own) |
| `django-secret-key` | Yes      | A random 50-character string                                                                   |
| `psql-password`     | Yes      | Password for the PostgreSQL database user                                                      |
| `redis-password`    | Yes      | Password for the Redis database                                                                |
| `server-crt`        | Yes      | Your TLS certificate in PEM format                                                             |
| `server-key`        | Yes      | Your TLS private key in PEM format                                                             |

### `oidc` — Single Sign-On / Identity Provider

| Key             | Required | Description                                                                        |
| --------------- | -------- | ---------------------------------------------------------------------------------- |
| `client-id`     | Yes      | OIDC client ID from your identity provider                                         |
| `client-secret` | Yes      | OIDC client secret from your identity provider                                     |
| `style`         | Yes      | Set to `manual` for Okta (or other OIDC providers), or `fusionauth` for FusionAuth |

If `style` is set to `manual`, fill out the `manual` section:

| Key                   | Required | Description                  |
| --------------------- | -------- | ---------------------------- |
| `logout-redirect-url` | Yes      | OIDC logout redirect URL     |
| `op-auth-endpoint`    | Yes      | Authorization endpoint       |
| `op-jwks-endpoint`    | Yes      | JWKS endpoint                |
| `op-token-endpoint`   | Yes      | Token endpoint               |
| `op-user-endpoint`    | Yes      | UserInfo endpoint            |
| `rp-token-endpoint`   | Yes      | Relying Party token endpoint |

If `style` is set to `fusionauth`, fill out the `fusionauth` section instead:

| Key          | Required | Description           |
| ------------ | -------- | --------------------- |
| `api-key`    | Yes      | FusionAuth API key    |
| `issuer-url` | Yes      | FusionAuth issuer URL |
| `tenant-id`  | Yes      | FusionAuth tenant ID  |

## Configure AI Providers

* `ai_provider_config.yaml` controls which AI providers Dropzone uses for investigations
* You should have already set the API keys for these providers in `config.yml`, the previous step
* Multiple providers deliver the best balance of performance, accuracy, and cost

Here you will use the `ai-model-tool` to explore valid model names and generate a ready-to-paste configuration snippet.

1. Perform an initial up:

```bash
/opt/dropzone/bin/deploy-dropzone up
```

1. Generate a config snippet for your provider:

```bash
/opt/dropzone/bin/ai-model-tool generate-config --provider <openai|anthropic|google|bedrock>
```

1. Paste the snippet into `/opt/dropzone/deploy/ai_provider_config.yaml` and fill in your deployment names
2. Validate that all model names are correct:

```bash
/opt/dropzone/bin/ai-model-tool validate-config
```

* To also verify live connectivity (auth and deployments), add `--check-connectivity`

1. If `validate-config` reports errors, fix the model names and run it again until it prints `OK: config is valid`

{% hint style="warning" %}
A typo under `models:` silently breaks the override for that model — a misspelled key means any custom `deployment_name`, per-model API key, or endpoint setting will never apply. Always validate before restarting.
{% endhint %}

### Provider Settings Reference

The settings and examples below are reference material for understanding what each field does. You can skip ahead if your config is already passing validation.

Each provider block accepts the following settings:

| Setting              | Description                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`            | `true`/`false` to enable or disable the provider                                                                                                                            |
| `platform`           | Deployment platform: `openai_api`, `azure_openai`, `anthropic_api`, `azure_anthropic`, `google_api`, `aws_bedrock`. Defaults to the provider's native API if not specified. |
| `endpoint`           | API endpoint URL (required for Azure-hosted platforms)                                                                                                                      |
| `api_key_var`        | Environment variable containing the API key                                                                                                                                 |
| `region`             | Geographic region (`us` or `eu`). Overrides the `ai-region` value from `config.yml` for this provider.                                                                      |
| `api_version`        | Azure API version override (has a sensible default)                                                                                                                         |
| `only_listed_models` | If `true`, only models explicitly listed under `models:` are available                                                                                                      |

### Configuration Examples

**Native OpenAI API (default):**

```yaml
providers:
  openai:
    enabled: true
  anthropic:
    enabled: false
  google:
    enabled: false
  bedrock:
    enabled: false
```

**Azure OpenAI** with a specific endpoint and model deployment names:

```yaml
providers:
  openai:
    platform: azure_openai
    endpoint: https://your-resource.openai.azure.com/
    api_key_var: DZ_AZURE_OPENAI_API_KEY
    only_listed_models: true
    models:
      gpt-4o:
        deployment_name: gpt4o-deployment
```

**Multiple providers** for better accuracy and cost balance:

```yaml
providers:
  openai:
    enabled: true
  anthropic:
    enabled: true
  google:
    enabled: false
  bedrock:
    enabled: false
```

**EU region** (overrides the global `ai-region` from `config.yml` for this provider):

```yaml
providers:
  openai:
    region: eu
```

**AWS Bedrock:**

```yaml
providers:
  bedrock:
    enabled: true
```

### Model-Level Overrides

Each provider can include a `models:` section to control which models are active and optionally override per-model settings.

When `only_listed_models: true` is set for a provider, each model you want enabled must appear under `models:` with `enabled: true`. Provider-level settings (`endpoint`, `api_key_var`, `api_version`) apply to all models by default — you only need to specify them per-model if you need to override them for specific models.

Available per-model settings: `enabled`, `deployment_name`, `endpoint`, `api_key_var`, `api_version`, `platform`, `input_cost_per_1k`, `output_cost_per_1k`.

* **`enabled`** — Required when `only_listed_models: true` is set; marks the model as active.
* **`deployment_name`** — Useful when your deployment name differs from the canonical model name (common with Azure or self-hosted models).
* **`endpoint` / `api_key_var`** — Advanced: override per-model if different models are deployed at different endpoints or use different credentials. Contact our Customer Success team if this applies to your setup.
* **`input_cost_per_1k` / `output_cost_per_1k`** — Override the built-in token pricing for a specific model (USD per 1,000 tokens). Use this when your deployment runs on a custom rate card that differs from standard API pricing — for example, a negotiated Azure enterprise agreement, GovCloud, or a private endpoint with different billing. Each field can be set independently; any field not set falls back to the built-in catalog rate. See [Per-model token cost overrides](#per-model-token-cost-overrides) below.

{% hint style="info" %}
The comments in `ai_provider_config.yaml` contain additional examples for each provider and platform combination. Engage our Customer Success team for guidance on the optimal provider configuration for your environment.
{% endhint %}

### Investigation Cost Limit

`investigation_cost_cap` is a top-level key (at the same level as `providers:`) that limits how much the system will spend on AI calls during the data-collection phase of a single investigation. When cumulative AI spend for an investigation reaches this limit, the investigation stops collecting additional evidence and proceeds directly to generating an outcome with what has been gathered so far.

| Key                      | Type        | Default | Description                                                             |
| ------------------------ | ----------- | ------- | ----------------------------------------------------------------------- |
| `investigation_cost_cap` | float (USD) | `20.0`  | Maximum AI spend per investigation during the evidence-collection phase |
| `cost_alert_threshold`   | float (USD) | `15.0`  | AI spend at which a warning is logged; does not stop the investigation  |

{% hint style="info" %}
Outcome generation (producing the final verdict and recommendations) runs after the cap is enforced and is not subject to this limit. The cap covers only the active investigation/evidence-collection phase.
{% endhint %}

The default `$20` cap is calibrated for standard OpenAI API pricing. If your deployment uses a provider or region with significantly higher per-token costs (e.g., AWS GovCloud IL5, Azure PSI, or enterprise-rate agreements), investigations may stop prematurely before gathering enough evidence. Raise the cap to match your effective token pricing.

```yaml
# Allow up to $50 of AI spend per investigation (default is $20)
investigation_cost_cap: 50.0
cost_alert_threshold: 40.0
providers:
  openai:
    enabled: true
  # ... other providers
```

**Backward compatibility:** The previous key name `global_cost_cap` is still accepted. If both keys are present, `investigation_cost_cap` takes precedence.

### Per-model token cost overrides

If your AI provider charges different per-token rates than Dropzone AI's built-in catalog prices, you can pin exact costs per model using `input_cost_per_1k` and `output_cost_per_1k` under a model's settings.

| Field                | Type        | Description                                                                          |
| -------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `input_cost_per_1k`  | float (USD) | Cost per 1,000 input (prompt) tokens. Falls back to catalog pricing if not set.      |
| `output_cost_per_1k` | float (USD) | Cost per 1,000 output (completion) tokens. Falls back to catalog pricing if not set. |

These fields are independent — you can set just one if only that side of your pricing differs. A warning is logged if only one is set, as a reminder that the other side is still using catalog rates.

```yaml
providers:
  openai:
    platform: azure_openai
    endpoint: https://your-resource.openai.azure.com/
    api_key_var: AZURE_OPENAI_API_KEY
    models:
      gpt-4o:
        deployment_name: gpt4o
        input_cost_per_1k: 0.005    # $0.005 per 1k input tokens
        output_cost_per_1k: 0.020   # $0.020 per 1k output tokens
```

{% hint style="info" %}
Cost overrides affect how Dropzone AI tracks spend against the `investigation_cost_cap`. They do not change what you are billed by your provider — set them to match what your provider actually charges so that the investigation cap reflects real costs.
{% endhint %}

After editing the config, run `ai-model-tool validate-config` to confirm the overrides are recognised. The command will print a summary of any active cost overrides:

```
Per-model cost overrides:
  openai:gpt-4o  input=$0.00500/1k  output=$0.02000/1k
```

For ongoing model management after initial setup — adding new models, updating provider config, and recovering from startup failures — see [Managing AI Providers](https://docs.dropzone.ai/edge/readme/ai-provider-management.md).

## Start Dropzone

Start (or restart) all services to apply your finalized configuration:

```bash
/opt/dropzone/bin/deploy-dropzone up
```

Monitor the startup logs in a separate terminal:

```bash
docker compose -p dz logs -f
```

To stop all services:

```bash
/opt/dropzone/bin/deploy-dropzone down
```

## (Optional) Start Dropzone at Boot

To start Dropzone automatically when the system boots, create a systemd service:

```bash
sudo tee /etc/systemd/system/dropzone.service <<'EOF'
[Unit]
Description=Run dropzone once at boot
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
User=ubuntu
ExecStart=/opt/dropzone/bin/deploy-dropzone up
RemainAfterExit=true

[Install]
WantedBy=multi-user.target
EOF
```

{% hint style="warning" %}
Replace `ubuntu` in the `User=` line with the username of your deployer user.
{% endhint %}

Enable the service:

```bash
sudo systemctl enable dropzone.service
```

## Local System Changes

Some Linux systems may require local changes to support the software requirements.

| Issue                                   | Change required                                                                                                                                                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| If you will be running Response Actions | See the [Response Actions Failing (AppArmor / SELinux)](https://docs.dropzone.ai/edge/readme/troubleshooting.md#response-actions-failing-apparmor-selinux) section to allowlist certain kernel security capabilities |
