For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installation

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:

sha256sum -c dropzone.tgz.sha256

This command can take a very long time, and will show no feedback until it's done reading the entire tarball.

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

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

This command can take a very long time, and will show no feedback until it's done reading the entire tarball.

  1. Run the installer

This creates the following directory structure:

Path
Purpose

/opt/dropzone/bin/

Deployment management scripts

/opt/dropzone/deploy/

Configuration files

/srv/dropzone/

Persistent application data

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

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:

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

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

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

Keys not relevant to your deployment can be left empty or at their default values.

connector — Connector Authentication

Generate connector secrets by running the provided script:

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

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:

  1. Generate a config snippet for your provider:

  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:

  • 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

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):

Azure OpenAI with a specific endpoint and model deployment names:

Multiple providers for better accuracy and cost balance:

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

AWS Bedrock:

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 below.

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.

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

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.

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.

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.

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.

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:

For ongoing model management after initial setup — adding new models, updating provider config, and recovering from startup failures — see Managing AI Providers.

Start Dropzone

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

Monitor the startup logs in a separate terminal:

To stop all services:

(Optional) Start Dropzone at Boot

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

Enable the 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) section to allowlist certain kernel security capabilities

Was this helpful?