Environment Variables

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

Environment variables (highest priority)
Command-line flags (e.g., --model)
~/.pensar/config.json (TUI settings)
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

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

Environment Variables

AI Provider Configuration

Anthropic (Claude)

OpenAI

OpenRouter

AWS Bedrock

Bearer Token Authentication

IAM Credentials Authentication

Local Models (vLLM)

Remote Execution Providers

Debugging and Development

CI/CD Configuration

GitHub Actions

GitLab CI

Docker

Configuration Priority

Example

Security Best Practices

Common Patterns

Per-Project Configuration

Multi-Provider Setup

Testing with Different Models

Environment Variable Files

Loading with `source`

Loading with `dotenv` (Node.js)

Troubleshooting

Quick Reference

Next Steps

AI Providers

Model Selection

Docker Setup

Run Pentest

Build docs developers (and LLMs) love

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

​AI Provider Configuration

​Anthropic (Claude)

​OpenAI

​OpenRouter

​AWS Bedrock

​Bearer Token Authentication

​IAM Credentials Authentication

​Local Models (vLLM)

​Remote Execution Providers

​Debugging and Development

​CI/CD Configuration

​GitHub Actions

​GitLab CI

​Docker

​Configuration Priority

​Example

​Security Best Practices

​Common Patterns

​Per-Project Configuration

​Multi-Provider Setup

​Testing with Different Models

​Environment Variable Files

​Loading with source

​Loading with dotenv (Node.js)

​Troubleshooting

​Quick Reference

​Next Steps

AI Providers

Model Selection

Docker Setup

Run Pentest

Build docs developers (and LLMs) love

AI Provider Configuration

Anthropic (Claude)

OpenAI

OpenRouter

AWS Bedrock

Bearer Token Authentication

IAM Credentials Authentication

Local Models (vLLM)

Remote Execution Providers

Debugging and Development

CI/CD Configuration

GitHub Actions

GitLab CI

Docker

Configuration Priority

Example

Security Best Practices

Common Patterns

Per-Project Configuration

Multi-Provider Setup

Testing with Different Models

Environment Variable Files

Loading with `source`

Loading with `dotenv` (Node.js)

Troubleshooting

Quick Reference

Next Steps