Guard

Configuration

Configure AIVory Guard to match your environment, from quick local setup to enterprise-grade deployments with custom compliance rules.

  • Environment variables control all settings - no config files required
  • Three deployment modes - Production (default), local development, or enterprise
  • 17 compliance standards checked automatically with customization options
  • Timeout tuning optimizes performance for different scan sizes
  • Security best practices keep your API keys safe

Environment Variables

AIVory Guard uses environment variables for all configuration. No config files needed.

Variable Description Default Required
AIVORY_API_KEY Your API authentication token (optional for free tier) - No
AIVORY_SERVER_URL Backend API URL https://app.aivory.net No
AIVORY_TIMEOUT Request timeout in milliseconds 30000 No
Note Free tier users can skip the API key entirely. Add one later to unlock premium features and higher rate limits.

Deployment Modes

Choose the configuration that matches your environment.

Production
Default mode. Connects to app.aivory.net with full feature access.
Local Development
Point to localhost:19999 for backend development and testing.
Enterprise Premium
Custom domain, SSO, private standards, and dedicated support.

Production Configuration (Default)

By default, AIVory Guard connects to the production backend. No AIVORY_SERVER_URL needed.

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "your_production_key"
      }
    }
  }
}

Get Your API Token

  1. Visit app.aivory.net/tokens
  2. Log in or create a free account
  3. Click Generate New Token
  4. Copy your API token
Note API tokens start with aiv_. Keep them secret and never commit them to version control.

Local Development Configuration

For backend development, point to your local instance.

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_SERVER_URL": "http://localhost:19999",
        "AIVORY_API_KEY": "your_local_dev_key"
      }
    }
  }
}
Alternative: Using .env Files

You can also use a .env file for local configuration:

# .env
AIVORY_SERVER_URL=http://localhost:19999
AIVORY_API_KEY=your_local_dev_key

Then reference variables in your MCP config:

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_SERVER_URL": "${AIVORY_SERVER_URL}",
        "AIVORY_API_KEY": "${AIVORY_API_KEY}"
      }
    }
  }
}

Enterprise Configuration

For custom or enterprise deployments with your own domain.

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_SERVER_URL": "https://aivory.yourcompany.com",
        "AIVORY_API_KEY": "your_enterprise_key"
      }
    }
  }
}
Custom Rules
Define compliance rules specific to your organization.
Private Standards
Create internal compliance standards not available publicly.
On-Premise
Host entirely within your infrastructure.
SSO Integration
Connect to your identity provider.
Retention Policies
Control how long scan data is stored.
Dedicated Support
Priority support with SLA guarantees.
Success Enterprise features require a paid plan. Contact sales for pricing and setup.

Timeout Configuration

Adjust request timeouts based on your scan sizes and network conditions.

Scan Size Recommended Timeout Use Case
Small (< 500 lines) 30000 (default) Single file quick checks
Large (500-2000 lines) 60000 Complex files with many patterns
Batch (multiple files) 120000 Scanning entire directories 
{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "your_key",
        "AIVORY_TIMEOUT": "60000"
      }
    }
  }
}
Note Start with the default 30-second timeout. Only increase if you see timeout errors during large batch scans.

Compliance Standards

AIVory Guard checks code against 17 compliance standards automatically.

Security
OWASP Top 10
Healthcare
HIPAA
Finance
PCI-DSS, SOC 2, AML, Geldwäschegesetz (GwG)
Privacy
GDPR, DSGVO, CCPA
Information Security
ISO 27001, ISO 27017, ISO 27018, TISAX
Regulatory
DORA, NIS2, EU AI Act, Hinweisgeberschutzgesetz (HinSchG)

Check Enabled Standards

Ask your AI assistant to show current configuration:

You: "What compliance standards are currently enabled?"

AI: [Uses get_config tool]

AI: "Currently checking against:
      OWASP Top 10, GDPR, DSGVO, HIPAA, CCPA,
      PCI-DSS, SOC 2, ISO 27001, ISO 27017, ISO 27018,
      TISAX, DORA, NIS2, EU AI Act, AML,
      Geldwäschegesetz (GwG), Hinweisgeberschutzgesetz (HinSchG)"
Customize Standards via API

When using the API directly, specify which standards to check:

// Scan with specific standards
const response = await fetch('https://app.aivory.net/api/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${AIVORY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: yourCode,
    language: 'python',
    standards: ['OWASP', 'GDPR', 'HIPAA']  // Only these 3
  })
});

Note: MCP integration currently checks all standards. Standard-specific filtering is available via direct API integration.

API Endpoints

AIVory Guard backend exposes these endpoints for direct integration.

Endpoint Method Purpose Authentication
/api/scan POST Scan single file Bearer token
/api/batch-scan POST Scan multiple files Bearer token
/api/config GET Get configuration Bearer token
/api/rules GET List compliance rules Bearer token
/api/health GET Health check None
Production Endpoints 
https://app.aivory.net/api/scan
https://app.aivory.net/api/batch-scan
https://app.aivory.net/api/config
https://app.aivory.net/api/rules
https://app.aivory.net/api/health
Local Development Endpoints 
http://localhost:19999/api/scan
http://localhost:19999/api/batch-scan
http://localhost:19999/api/config
http://localhost:19999/api/rules
http://localhost:19999/api/health

Testing Your Configuration

Verify everything works correctly before using AIVory Guard.

npx @aivorynet/guard test

Expected Output

✓ Configuration loaded
✓ Server: https://app.aivory.net
✓ Backend is healthy
✓ Compliance scan completed

All tests passed! ✅
Troubleshooting Test Failures

“Configuration not found”

  • Run npx @aivorynet/guard init to create config
  • Ensure .env file exists or environment variables are set

“Invalid API key”

  • Verify API key starts with aiv_
  • Generate new token at app.aivory.net/tokens
  • Check for spaces or hidden characters

“Connection timeout”

  • Check internet connectivity
  • Verify server URL is correct
  • Try increasing timeout with AIVORY_TIMEOUT=60000
  • Check firewall/proxy settings

“Backend unhealthy”

  • Verify backend is running (for local dev)
  • Check status.aivory.net (for production)
  • Try again in a few minutes

Multiple Environments

Manage different configurations for development, staging, and production.

Config Files
Separate .env files per environment (.env.development, .env.staging, .env.production)
Shell Scripts
Wrapper scripts that set variables before launching your AI tool
Environment-Specific Config Files 
# .env.development
AIVORY_SERVER_URL=http://localhost:19999
AIVORY_API_KEY=dev_key

# .env.staging
AIVORY_SERVER_URL=https://staging.aivory.net
AIVORY_API_KEY=staging_key

# .env.production
AIVORY_SERVER_URL=https://app.aivory.net
AIVORY_API_KEY=prod_key

Load the appropriate file based on your environment.

Shell Script Approach 
#!/bin/bash
# start-dev.sh

export AIVORY_SERVER_URL=http://localhost:19999
export AIVORY_API_KEY=dev_key
claude-code .

#!/bin/bash
# start-prod.sh

export AIVORY_SERVER_URL=https://app.aivory.net
export AIVORY_API_KEY=prod_key
claude-code .

Security Best Practices

Keep your API keys and configuration secure.

Never Commit Keys
Add .env to .gitignore immediately
Use Env Variables
Don’t hardcode keys in config files
Rotate Regularly
Generate new tokens every 90 days
Separate Keys
Different keys for dev/staging/prod
Restrict Permissions
Use role-based access control (enterprise)
Monitor Usage
Check logs at app.aivory.net/logs
Warning Never share your API key in screenshots, logs, or support requests. Regenerate immediately if exposed.

Advanced Configuration

Custom HTTP Headers (Enterprise)

Enterprise customers can add custom headers for internal routing or identification:

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "enterprise_key",
        "AIVORY_CUSTOM_HEADERS": "{\"X-Company-ID\":\"12345\"}"
      }
    }
  }
}
Proxy Configuration

For networks requiring proxies:

# Set via environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

# Then start your AI tool
claude-code .
SSL/TLS Certificate Verification

Disable SSL verification for self-signed certificates (development only):

{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "your_key",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}
Warning Only use this in controlled development environments. Never disable SSL verification in production.
Migration Between Environments

From Local to Production:

  1. Generate production token at app.aivory.net/tokens
  2. Update environment variables: 
    AIVORY_SERVER_URL=https://app.aivory.net
AIVORY_API_KEY=prod_key
  3. Test connection: npx @aivorynet/guard test
  4. Restart your AI tool

From Production to Local:

  1. Start local backend on port 19999
  2. Generate local API token
  3. Update environment variables: 
    AIVORY_SERVER_URL=http://localhost:19999
AIVORY_API_KEY=local_key
  4. Test connection: npx @aivorynet/guard test
  5. Restart your AI tool

Next Steps

Usage Guide
Learn how to scan code and interpret results
API Reference
Complete API documentation for direct integration
Integration Guides
Tool-specific setup for your IDE or AI assistant
Note Need help? Contact support or check the FAQ for common questions.