Environment Variables

Complete reference of all environment variables for configuring Pensar Apex

Pensar Apex can be configured using environment variables. This is the recommended approach for CLI usage, CI/CD pipelines, and containerized deployments.

Environment variables always take precedence over TUI configuration stored in ~/.pensar/config.json.

AI Provider Configuration

Anthropic (Claude)

ANTHROPIC_API_KEY · string · required

Anthropic API key for Claude models.

export ANTHROPIC_API_KEY="sk-ant-..."

Get your key at console.anthropic.com.

OpenAI

OPENAI_API_KEY · string

OpenAI API key for GPT models.

export OPENAI_API_KEY="sk-..."

Get your key at platform.openai.com/api-keys.

OpenRouter

OPENROUTER_API_KEY · string

OpenRouter API key for accessing multiple model providers.

export OPENROUTER_API_KEY="sk-or-..."

Get your key at openrouter.ai.

AWS Bedrock

Bearer Token Authentication

BEDROCK_API_KEY · string

Bearer token for Bedrock API access.

export BEDROCK_API_KEY="your-bearer-token"
export AWS_REGION="us-east-1"

IAM Credentials Authentication

AWS_ACCESS_KEY_ID · string

AWS access key ID for IAM authentication.

export AWS_ACCESS_KEY_ID="AKIA..."

AWS_SECRET_ACCESS_KEY · string

AWS secret access key for IAM authentication.

export AWS_SECRET_ACCESS_KEY="..."

AWS_SESSION_TOKEN · string

AWS session token for temporary credentials (optional).

export AWS_SESSION_TOKEN="..."

Required only when using temporary credentials from AWS STS.

AWS_REGION · string · default: "us-east-1"

AWS region for Bedrock API.

export AWS_REGION="us-east-1"

Common regions: us-east-1, us-west-2, eu-west-1.

Local Models (vLLM)

LOCAL_MODEL_URL · string

vLLM server endpoint URL.

export LOCAL_MODEL_URL="http://localhost:8000/v1"

Must point to an OpenAI-compatible API endpoint.

Remote Execution Providers

These are optional enterprise features for distributed pentesting. Most users don’t need them.

DAYTONA_API_KEY · string

Daytona API key for remote agent execution.

export DAYTONA_API_KEY="..."

DAYTONA_ORG_ID · string

Daytona organization ID.

export DAYTONA_ORG_ID="org_..."

RUNLOOP_API_KEY · string

Runloop API key for remote execution.

export RUNLOOP_API_KEY="..."

Debugging and Development

PENSAR_DEBUG · string · default: "false"

Enable debug logging.

export PENSAR_DEBUG="true"
pensar pentest --target https://example.com

Outputs detailed agent execution logs to console.

SHOW_CONSOLE · string · default: "false"

Show console output in TUI development mode.

export SHOW_CONSOLE="true"
bun run dev

Used only for TUI development.

CI/CD Configuration

GitHub Actions

Store API keys as repository secrets:

.github/workflows/pentest.yml

name: Pentest

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Pensar Apex
        run: npm install -g @pensar/apex

      - name: Run Pentest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          pensar pentest \
            --target https://staging.example.com \
            --cwd . \
            --model claude-sonnet-4-5

      - name: Upload Results
        uses: actions/upload-artifact@v4
        with:
          name: pentest-results
          path: ~/.pensar/sessions/**/findings/

GitLab CI

.gitlab-ci.yml

pentest:
  image: node:18
  before_script:
    - npm install -g @pensar/apex
  script:
    - pensar pentest --target https://staging.example.com --cwd .
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  artifacts:
    paths:
      - ~/.pensar/sessions/**/findings/
    expire_in: 30 days
  only:
    - schedules

Docker

Pass environment variables to the container:

docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  pensarai/apex \
  pensar pentest --target https://example.com --cwd /workspace

Or use an .env file:

.env

ANTHROPIC_API_KEY=sk-ant-...
AWS_REGION=us-east-1

# Load from .env file
docker run -it --env-file .env pensarai/apex pensar pentest --target https://example.com

Configuration Priority

When multiple configuration sources are present, Pensar Apex uses this priority order (highest to lowest):

1. Environment variables (highest priority)
2. Command-line flags (e.g., --model)
3. ~/.pensar/config.json (TUI settings)
4. Default values (lowest priority)

Example

# Config file has: "selectedModelId": "claude-sonnet-3-5"
# Environment has: ANTHROPIC_API_KEY=...
# Command-line has: --model claude-opus-4

pensar pentest --target https://example.com --model claude-opus-4

# Result: Uses claude-opus-4 (command-line overrides config file)

Security Best Practices

Never commit API keys to version control

Use .gitignore to exclude environment files:

.gitignore

.env
.env.local
.pensar/config.json

Use secret management in CI/CD instead of hardcoding keys.

Use separate keys for different environments

# Development
export ANTHROPIC_API_KEY="sk-ant-dev-..."

# Production
export ANTHROPIC_API_KEY="sk-ant-prod-..."

This allows tracking usage and revoking keys per environment.

Rotate API keys regularly

# Generate new key at provider console
# Update environment variable
export ANTHROPIC_API_KEY="sk-ant-new-..."

# Test new key
pensar doctor

# Revoke old key at provider console

Rotate keys every 90 days or when team members leave.

Use IAM roles instead of static credentials (AWS)

For EC2, ECS, or Lambda deployments:

# No need to set AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY
# IAM role credentials are automatically discovered
export AWS_REGION="us-east-1"
pensar pentest --target https://example.com

Attach an IAM role with bedrock:InvokeModel permission.

Encrypt environment files

If you must store .env files locally:

# Encrypt
gpg -c .env

# Decrypt when needed
gpg .env.gpg
source .env

Better: Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.).

Common Patterns

Per-Project Configuration

Create a .env file per project:

my-project/.env

ANTHROPIC_API_KEY=sk-ant-...
TARGET_URL=https://staging.myapp.com
SOURCE_PATH=/path/to/source

# Load and run
source .env
pensar pentest --target "$TARGET_URL" --cwd "$SOURCE_PATH"

Multi-Provider Setup

Configure all providers for fallback:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."

# Pensar will use Anthropic by default
# Falls back to OpenAI if Anthropic fails

Testing with Different Models

# Set provider keys once
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Test with different models
pensar pentest --target https://example.com --model claude-sonnet-4-5
pensar pentest --target https://example.com --model gpt-4
pensar pentest --target https://example.com --model claude-opus-4

Environment Variable Files

Loading with source

# Create .env
cat > .env <<EOF
ANTHROPIC_API_KEY=sk-ant-...
AWS_REGION=us-east-1
EOF

# Load into current shell
source .env

# Run pentest
pensar pentest --target https://example.com

Loading with dotenv (Node.js)

For programmatic usage:

import { config } from 'dotenv';
import { runPentestAgent } from '@pensar/apex';

// Load .env file
config();

// Environment variables are now available
const result = await runPentestAgent({
  target: process.env.TARGET_URL!,
  model: 'claude-sonnet-4-5',
  // authConfig is automatically built from process.env
});

Troubleshooting

Environment variable not recognized

Verify the variable is exported:

# Check if set
echo $ANTHROPIC_API_KEY

# If empty, export it
export ANTHROPIC_API_KEY="sk-ant-..."

# Verify again
echo $ANTHROPIC_API_KEY

Variables must be exported to be visible to child processes.

API key works in shell but not in TUI

Ensure the variable is exported before launching the TUI:

# Wrong:
ANTHROPIC_API_KEY=sk-ant-... pensar  # Variable not exported

# Right:
export ANTHROPIC_API_KEY=sk-ant-...
pensar

Variables not persisting across sessions

Add exports to your shell profile:

# For bash
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

Better: Use a secrets manager or environment manager like direnv.

AWS credentials not working

For IAM credentials, verify all required variables:

echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
echo $AWS_REGION

# Test with AWS CLI
aws sts get-caller-identity

If AWS CLI works but Pensar doesn’t, check that credentials have bedrock:InvokeModel permission.

Quick Reference

Variable	Required	Description
ANTHROPIC_API_KEY	Yes*	Anthropic API key (recommended)
OPENAI_API_KEY	Yes*	OpenAI API key
OPENROUTER_API_KEY	Yes*	OpenRouter API key
BEDROCK_API_KEY	Yes*	AWS Bedrock bearer token
AWS_ACCESS_KEY_ID	Yes*	AWS IAM access key
AWS_SECRET_ACCESS_KEY	Yes*	AWS IAM secret key
AWS_SESSION_TOKEN	No	AWS temporary session token
AWS_REGION	No	AWS region (default: us-east-1)
LOCAL_MODEL_URL	Yes*	vLLM server endpoint
PENSAR_DEBUG	No	Enable debug logging

*At least one AI provider key is required.

Next Steps

AI Providers

Learn about each supported provider

Model Selection

Choose the right model for your needs

Docker Setup

Use environment variables in containers

Run Pentest

Start testing with your configuration