Configuration

powerglide resolves configuration through four layers in strict precedence order. The design intent is that your persistent preferences live in the config file, system-wide or CI overrides live in environment variables, and per-invocation changes go on the command line — each layer wins over everything below it without clobbering it.

Configuration Precedence

Configuration loads in the following order (highest to lowest priority):

1. Command-line arguments — Override everything. Useful for one-off sessions without touching persistent config.
2. Environment variables — System-wide settings, shared across all sessions. The natural home for API keys.
3. Config file — ~/.config/powerglide/config.json — User preferences that persist across sessions.
4. Built-in defaults — Fallback values when nothing else specifies a setting.

Environment Variables

API keys belong here rather than in the config file — environment variables don’t get accidentally committed to version control, and they’re easy to rotate per-machine or per-CI-job without touching a shared config. Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Default Settings
export POWERGLIDE_MODEL="claude-opus-4-6"
export POWERGLIDE_VELOCITY="1.0"
export POWERGLIDE_MAX_STEPS="200"

Available Variables

Config File

The config file is the right home for preferences that should persist: your default agent, velocity, model provider, and safety limits. It’s read on every invocation and merged with the layers above it.

Location: ~/.config/powerglide/config.json

{
  "default_agent": "hephaestus",
  "velocity": 1.0,
  "max_steps": 200,
  "model": {
    "provider": "anthropic",
    "model": "claude-opus-4-6"
  },
  "fallback_chain": [
    { "provider": "anthropic", "model": "claude-sonnet-4" },
    { "provider": "openai", "model": "gpt-4" }
  ],
  "tools": {
    "bash": {
      "timeout": 30000,
      "max_output": 10000
    },
    "read": {
      "max_size": 1048576
    }
  }
}

Configuration Schema

{
  "default_agent": "string (agent name)",
  "velocity": "float (multiplier)",
  "max_steps": "integer",
  "model": {
    "provider": "anthropic | openai | openai_compatible",
    "model": "string (model name)",
    "base_url": "string (optional, for OpenAI-compatible)"
  },
  "fallback_chain": "array of model configs",
  "tools": {
    "bash": { "timeout": "ms", "max_output": "bytes" },
    "read": { "max_size": "bytes" },
    "edit": { "max_edits": "integer" }
  },
  "rogue_prevention": {
    "step_limit": "integer",
    "heartbeat_timeout": "ms",
    "circuit_breaker_threshold": "integer"
  }
}

Session Configuration

Each running session writes its own JSON file at ~/.config/powerglide/session-<id>.json. This file serves two purposes: it’s the authoritative record of the session’s current state, and it’s the mechanism through which agents self-adjust velocity mid-session. The orchestrator polls it on each loop iteration.

{
  "id": "abc123",
  "agent": "hephaestus",
  "velocity": 1.5,
  "model": "claude-opus-4-6",
  "created_at": "2026-03-02T10:00:00Z",
  "last_activity": "2026-03-02T10:30:00Z",
  "steps_completed": 42,
  "status": "active"
}

steps_completed is how the step-limit safety check tracks progress. last_activity is updated on each loop iteration and is what the heartbeat monitor compares against heartbeat_timeout to detect stalled sessions.

Model Providers

powerglide supports three provider modes. Anthropic and OpenAI use their respective native APIs; openai_compatible uses the same OpenAI request format but with a configurable base_url, which means any endpoint that speaks /v1/chat/completions — Ollama, NVIDIA NIM, Together AI, LM Studio, vLLM — works without any code changes.

Anthropic (Claude)

export ANTHROPIC_API_KEY="sk-ant-..."
export POWERGLIDE_MODEL="claude-opus-4-6"

OpenAI

export OPENAI_API_KEY="sk-..."
export POWERGLIDE_MODEL="gpt-4"

OpenAI-Compatible (Ollama, NVIDIA NIM, Together AI)

export OPENAI_API_KEY="..."
export POWERGLIDE_MODEL="ollama/llama3"

# Config file
{
  "model": {
    "provider": "openai_compatible",
    "base_url": "http://localhost:11434/v1",
    "model": "llama3"
  }
}

Tool Configuration

Tool-specific configuration limits the blast radius of individual tool calls. The bash tool’s timeout prevents a hung subprocess from blocking the loop indefinitely; max_output prevents a verbose command from flooding the model’s context window. blocked_commands is a pattern list applied before execution — a last-resort guardrail against obviously dangerous invocations.

Bash Tool

{
  "tools": {
    "bash": {
      "timeout": 30000,
      "max_output": 10000,
      "allowed_commands": ["*"],
      "blocked_commands": ["rm -rf /", "dd if=/dev/zero"]
    }
  }
}

Read Tool

{
  "tools": {
    "read": {
      "max_size": 1048576,
      "allowed_patterns": ["*"],
      "blocked_patterns": ["/etc/passwd", "~/.ssh/*"]
    }
  }
}

Rogue Prevention

The rogue prevention settings form a layered safety net. No single mechanism catches every failure mode, so powerglide uses several independent checks that operate simultaneously.

{
  "rogue_prevention": {
    "step_limit": 200,
    "heartbeat_timeout": 30000,
    "circuit_breaker_threshold": 3,
    "budget": {
      "max_tokens": 100000,
      "max_cost_usd": 10.00
    }
  }
}

• step_limit — Hard ceiling on loop iterations. An agent making one tool call per step hits this at 200 tool calls. Raise it for large tasks; lower it for exploratory runs you want to review.
• heartbeat_timeout — Milliseconds since last_activity before the monitor considers a worker stalled. 30s is conservative; a hung subprocess would miss this quickly.
• circuit_breaker_threshold — If the same tool is called with identical arguments N times in a row, the loop is definitionally stuck. 3 repetitions is usually enough signal.
• budget.max_tokens — Aggregate token count across the session. Useful for preventing runaway cost on tasks that unexpectedly expand in scope.
• budget.max_cost_usd — Estimated USD cost ceiling. The router tracks approximate cost per model based on published token pricing.

Editing Configuration

Use the CLI to manage configuration:

# Show current config
powerglide config show

# Set a value
powerglide config set default_agent hephaestus

# Get a value
powerglide config get velocity

# Reset to defaults
powerglide config reset

# Edit config file directly
powerglide config edit

Back to Home · CLI Reference · For AI Agents