Skip to main content

​
Docker Deployment

The simplest way to run the FailZero agent. Works anywhere Docker runs.

​
Quick Start

docker run -d \
  --name failzero-agent \
  --restart unless-stopped \
  -e FAILZERO_AGENT_TOKEN=fzat_your_token \
  -e FAILZERO_API_URL=https://api.failzero.io \
  -e PROVIDER_TYPE=gcp \
  -e GCP_PROJECT_ID=your-project \
  failzero/agent:latest

​
Environment Variables

​
Required

VariableDescription
FAILZERO_AGENT_TOKENAgent token from dashboard (fzat_...)
FAILZERO_API_URLFailZero API endpoint (https://api.failzero.io)
PROVIDER_TYPECloud provider: gcp or aws

​
GCP

VariableDescription
GCP_PROJECT_IDYour GCP project ID
GCP_REGIONRegion (default: us-west1)

​
AWS

VariableDescription
AWS_ACCOUNT_IDYour AWS account ID
AWS_REGIONRegion (default: us-east-1)

​
Optional

VariableDescriptionDefault
HEALTH_CHECK_INTERVALHealth check frequency (ms)30000
COMMAND_POLL_INTERVALCommand poll frequency (ms)5000

​
Docker Compose

For local development or simple deployments: 
version: '3.8'
services:
  failzero-agent:
    image: failzero/agent:latest
    restart: unless-stopped
    environment:
      FAILZERO_AGENT_TOKEN: ${FAILZERO_AGENT_TOKEN}
      FAILZERO_API_URL: https://api.failzero.io
      PROVIDER_TYPE: gcp
      GCP_PROJECT_ID: ${GCP_PROJECT_ID}
    volumes:
      # Mount GCP credentials (if not using metadata server)
      - ~/.config/gcloud:/root/.config/gcloud:ro
When running outside GCP, mount your service account credentials or set GOOGLE_APPLICATION_CREDENTIALS.

​
Credentials

​
GCP

Inside GCP (recommended): The agent automatically uses the VM’s service account via metadata server. No configuration needed. Outside GCP: Mount credentials or set environment variable: 
docker run -d \
  --name failzero-agent \
  -v /path/to/service-account.json:/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \
  -e FAILZERO_AGENT_TOKEN=fzat_your_token \
  -e FAILZERO_API_URL=https://api.failzero.io \
  -e PROVIDER_TYPE=gcp \
  -e GCP_PROJECT_ID=your-project \
  failzero/agent:latest

​
AWS

Inside AWS (recommended): The agent automatically uses the instance role or task role. No configuration needed. Outside AWS: Set credentials via environment: 
docker run -d \
  --name failzero-agent \
  -e AWS_ACCESS_KEY_ID=AKIA... \
  -e AWS_SECRET_ACCESS_KEY=... \
  -e FAILZERO_AGENT_TOKEN=fzat_your_token \
  -e FAILZERO_API_URL=https://api.failzero.io \
  -e PROVIDER_TYPE=aws \
  -e AWS_ACCOUNT_ID=123456789012 \
  failzero/agent:latest

​
Verify Deployment

Check agent status: 
# View logs
docker logs failzero-agent

# Check running status
docker ps | grep failzero-agent
Expected log output: 
[Agent] Starting FailZero Agent...
[Agent] Registering with FailZero API...
[Agent] Registered successfully for organization: your-org
[Agent] Agent started successfully

​
Troubleshooting

Agent won’t start:
  • Verify FAILZERO_AGENT_TOKEN is correct
  • Check network connectivity to api.failzero.io
  • Review logs: docker logs failzero-agent
Authentication errors:
  • Inside GCP/AWS: Verify IAM roles are attached
  • Outside cloud: Check mounted credentials are valid
Health checks failing:
  • Ensure agent can reach monitored endpoints
  • Check firewall rules allow outbound HTTPS

​
Next Steps

IAM Setup

Configure GCP service account permissions

Example Plans

Real-world DR configurations