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.sha256You 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
Extract the installer from the deployment package
tar -xzf dropzone.tgz --occurrence=1 dropzone-ai/deploy-dropzoneRun the installer
This creates the following directory structure:
/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.
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
Additional optional keys in this section support specific integrations:
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
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
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
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
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:
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:
api-key
Yes
FusionAuth API key
issuer-url
Yes
FusionAuth issuer URL
tenant-id
Yes
FusionAuth tenant ID
Configure AI Providers
ai_provider_config.yamlcontrols which AI providers Dropzone uses for investigationsYou should have already set the API keys for these providers in
config.yml, the previous stepMultiple 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.
Perform an initial up:
Generate a config snippet for your provider:
Paste the snippet into
/opt/dropzone/deploy/ai_provider_config.yamland fill in your deployment namesValidate that all model names are correct:
To also verify live connectivity (auth and deployments), add
--check-connectivity
If
validate-configreports errors, fix the model names and run it again until it printsOK: 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:
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 whenonly_listed_models: trueis 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.
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.
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
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.
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.
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.
If you will be running Response Actions
See the Response Actions Failing (AppArmor / SELinux) section to allowlist certain kernel security capabilities
Was this helpful?