Provider Configuration

SwarmVault does not require provider configuration to start. The built-in heuristic provider is always available for local/offline workflows.

The providers object in your config maps provider names to their configuration when you want higher-quality synthesis or extra capabilities such as embeddings, vision, image generation, or a specific hosted backend.

This page covers LLM providers. Deep-lint web augmentation uses a separate webSearch block documented in Web Search.

CLI Provider Registry

Use the provider registry commands when you want to update swarmvault.config.json without hand-editing JSON:

swarmvault provider add fast --type openai --model gpt-4o-mini --api-key-env OPENAI_API_KEY --capability chat --capability structured --task queryProvider
swarmvault provider list
swarmvault provider show fast
swarmvault provider remove fast --fallback local

provider add validates provider type, declared capabilities, and task assignments before writing the config. It stores only environment variable names for secrets; literal API key values are rejected. Unknown top-level config fields are preserved.

provider remove deletes a provider and reassigns any tasks that pointed at it to --fallback, or to local when that built-in provider is present.

Provider Config Fields

Field	Required	Description
`type`	Yes	Provider type (see below)
`model`	Yes	Model identifier
`baseUrl`	No	Custom API base URL
`apiKeyEnv`	No	Environment variable name for API key
`headers`	No	Additional HTTP headers
`module`	No	Path to custom provider module
`capabilities`	No	Explicit capability list
`apiStyle`	No	`"responses"` or `"chat"` for OpenAI-style providers

Common capabilities include chat, structured, vision, embeddings, image_generation, and audio.

Built-In Provider Types

heuristic
openai
anthropic
gemini
ollama
openrouter
groq
together
xai
cerebras
local-whisper
openai-compatible
custom

Example: Multiple Providers

{
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1"
    },
    "openai": {
      "type": "openai",
      "model": "gpt-4o",
      "apiKeyEnv": "OPENAI_API_KEY"
    },
    "claude": {
      "type": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    },
    "openrouter": {
      "type": "openrouter",
      "model": "openai/gpt-4o-mini"
    }
  },
  "tasks": {
    "compileProvider": "openai",
    "queryProvider": "claude",
    "lintProvider": "local",
    "visionProvider": "openai",
    "imageProvider": "openai",
    "embeddingProvider": "openrouter"
  }
}

Each task can use a different provider. The local heuristic provider is always available as the built-in local path. imageProvider is optional unless you want native raster image generation for --format image, and embeddingProvider is optional unless you want semantic graph query and embedding-backed similarity enrichment.

audioProvider is the parallel optional task for audio-file ingest. By default, SwarmVault treats openai, ollama, groq, and generic openai-compatible providers as audio-capable unless you override their declared capabilities explicitly.

Local Embeddings Without API Keys

Use an embedding-capable local backend for tasks.embeddingProvider. heuristic is a valid local default for compile/query/lint, but it does not provide embeddings.

{
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1"
    },
    "ollama-embeddings": {
      "type": "ollama",
      "model": "nomic-embed-text",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "compileProvider": "local",
    "queryProvider": "local",
    "embeddingProvider": "ollama-embeddings"
  }
}