Provider & configuration management

Set up your LLM providers, build environment profiles, manage verification toolchain binaries, and keep your installation healthy.

Difficulty: Beginner Duration: 25 minutes What you’ll build: A multi-provider setup with named profiles for production, staging, and local development — plus a verification toolchain ready for CI use

What you’ll learn

How to add, switch, and configure fallback providers
Why named profiles exist and how to use them to isolate environments
How the toolchain works and when to pre-install binaries vs. let DojOps auto-install them
How to read dojops status output to diagnose setup issues
Which environment variables override which config settings

Prerequisites

DojOps 1.1.6 installed: npm i -g @dojops/cli
API keys for the providers you want to use

Workshop steps

Step 1: Check what’s currently configured

Before adding anything, see the current provider state:


dojops provider


┌  LLM Providers
│
│  openai          ✓ configured (default)
│  anthropic       ✗ not configured
│  ollama          ✗ not configured
│  deepseek        ✗ not configured
│  gemini          ✗ not configured
│  github-copilot  ✗ not configured
│
└  1 configured, 1 default

DojOps supports 7 providers. Each maps to a different API authentication scheme and different model naming conventions. You only need to configure the ones you plan to use.

Get JSON output when scripting:


dojops provider list --output json

Step 2: Add a provider

Add Anthropic using its API key:


dojops provider add anthropic --token sk-ant-api03-yourkey


┌  Provider Added
│
│  Provider: anthropic
│  Status: ✓ configured
│
└  Token saved to ~/.dojops/config.json

The token is written to ~/.dojops/config.json — your global DojOps configuration. Environment variables take precedence over this file, so you can override per-session:


export ANTHROPIC_API_KEY=sk-ant-api03-yourkey
export DEEPSEEK_API_KEY=sk-deepseek-yourkey
export GEMINI_API_KEY=AIzaSy-yourkey

After adding Anthropic, check the provider list again — it should now show both OpenAI and Anthropic as configured.

Step 3: Switch the default provider

Use the interactive picker to change which provider runs by default:


dojops provider switch


◆  Select default provider:
│  ● openai (current)
│  ○ anthropic
│  ○ ollama

Or set it directly without the prompt:


dojops provider default anthropic

From this point, every dojops command uses Anthropic unless you override it. Verify:


dojops provider


┌  LLM Providers
│
│  openai     ✓ configured
│  anthropic  ✓ configured (default)
│  ...
│
└  2 configured, 1 default

Step 4: Override the provider for a single command

Switching the default changes every future command. For a one-off override without changing defaults, use the --provider flag:


dojops --provider=openai "Create a Terraform config for S3"
dojops --provider=anthropic "Create a Dockerfile for Python"
dojops --model=gpt-4o-mini "Create a simple .gitignore"

Temperature works the same way — set it globally in config or override per-command:


dojops --temperature=0 "Create a Kubernetes deployment"

--temperature=0 is useful when you want deterministic output for review or testing.

Step 5: Configure a fallback provider

A fallback provider activates when the primary fails — rate limits, network errors, API outages. Set it per-command or globally:


# Per-command fallback
dojops --fallback-provider=ollama "Create a CI workflow"
 
# Global fallback via environment variable
export DOJOPS_FALLBACK_PROVIDER=ollama

When a fallback triggers, DojOps logs a warning and proceeds:


⚠ Primary provider (anthropic) failed: rate limit exceeded
  Falling back to: ollama
  Retrying...

Ollama works well as a local fallback because it has no API costs and no rate limits. Set it up with dojops provider add ollama and point OLLAMA_HOST at your local Ollama instance.

Step 6: Authenticate with GitHub Copilot

GitHub Copilot uses OAuth Device Flow instead of an API key. Trigger the flow:


dojops auth login --provider github-copilot


┌  GitHub Copilot Authentication
│
│  Open this URL in your browser:
│  https://github.com/login/device
│
│  Enter code: ABCD-1234
│
│  Waiting for authorization...
│  ✓ Authenticated as @your-username
│
└  Token saved to ~/.dojops/copilot-token.json

The token is persisted to ~/.dojops/copilot-token.json and auto-refreshed on expiry. In CI environments where the browser flow isn’t possible, bypass it with:


export GITHUB_COPILOT_TOKEN=your-oauth-token

Check authentication status at any time:


dojops auth status

Step 7: View the active configuration

See the full picture of your current settings:


dojops config show


┌  Configuration
│
│  Provider: anthropic
│  Model: claude-sonnet-4-6 (default for provider)
│  Temperature: (not set)
│  Fallback: ollama
│  Profile: (default)
│
└  Active configuration

When Temperature shows (not set), the provider’s default is used — typically around 0.7 for most providers.

Step 8: Create environment profiles

Profiles let you save a complete configuration state — provider, model, temperature, fallback — and switch between them by name. They’re most useful when you work across multiple environments that need different LLM setups.

With Anthropic as your current default, save a staging profile:


dojops config profile create staging


┌  Profile Created
│
│  Name: staging
│  Provider: anthropic
│  Model: claude-sonnet-4-6
│
└  Saved - use `dojops config profile use staging` to activate

Switch to OpenAI and save a production profile:


dojops provider default openai
dojops config profile create production

Switch to Ollama for local development:


dojops provider default ollama
dojops config profile create local-dev

Now you have three profiles:


dojops config profile list


┌  Configuration Profiles
│
│  default     openai / gpt-4o
│  production  openai / gpt-4o
│  staging     anthropic / claude-sonnet-4-6
│  local-dev   ollama / llama3.1
│
└  4 profiles (default is active)

Step 9: Activate and use profiles

Switch to a profile:


dojops config profile use staging

All subsequent commands now use Anthropic. Switch back to the default:


dojops config profile use default

For one-off profile use without changing the active profile:


dojops --profile=production "Create a Terraform config"
dojops --profile=local-dev "Create a Dockerfile"

This is useful in scripts that need to test output from multiple providers without changing global state.

Step 10: Remove a provider

When you no longer need a provider:


dojops provider remove deepseek

The token is removed from ~/.dojops/config.json. If you had DEEPSEEK_API_KEY set as an environment variable, it still works — environment variables aren’t touched by this command.

Step 11: Explore the toolchain

DojOps can verify generated configs using external tools — terraform validate, actionlint, hadolint, etc. These run after generation, before writing files. See what’s available:


dojops toolchain list


┌  System Toolchain (~/.dojops/toolchain/)
│
│  terraform   ✗ not installed  (v1.9.8)
│  kubectl     ✗ not installed  (v1.31.4)
│  helm        ✗ not installed  (v3.17.3)
│  hadolint    ✗ not installed  (v2.12.0)
│  trivy       ✗ not installed  (v0.58.2)
│  gitleaks    ✗ not installed  (v8.22.1)
│  ansible     ✗ not installed  (v11.1.0)
│  shellcheck  ✗ not installed  (v0.10.0)
│  actionlint  ✗ not installed  (v1.7.7)
│  promtool    ✗ not installed  (v2.55.1)
│  circleci    ✗ not installed  (v0.1.31364)
│  gh          ✗ not installed  (v2.63.2)
│
└  0 installed, 12 available

All binaries install to ~/.dojops/toolchain/ — they don’t touch your system PATH unless you add that directory yourself.

Step 12: Install toolchain binaries

Install the tools you use most often. For a CI/CD-focused setup:


dojops toolchain install actionlint
dojops toolchain install hadolint
dojops toolchain install shellcheck


┌  Installing: actionlint v1.7.7
│
│  Downloading from github.com/rhysd/actionlint...
│  Extracting to ~/.dojops/toolchain/actionlint
│  ✓ Installed: actionlint v1.7.7
│
└  Ready - used for CI workflow verification in apply

For infrastructure-focused work, install Terraform and Helm:


dojops toolchain install terraform
dojops toolchain install helm

You don’t have to pre-install anything. When dojops apply runs a verification step and the required binary is missing, it installs it automatically on first use. Manual pre-installation is useful for CI environments where you want to control what gets downloaded during the build, or for air-gapped setups where you need to pre-populate the toolchain.

Remove a binary you no longer need:


dojops toolchain remove terraform

Wipe the entire toolchain to start fresh:


dojops toolchain clean

Step 13: Run system diagnostics

Get a complete health report of your DojOps installation:


dojops status


┌  DojOps Status
│
│  Version: v1.1.6
│  Node.js: v20.11.0
│
│  Provider: anthropic ✓ connected
│  Model: claude-sonnet-4-6
│  Fallback: ollama
│
│  Project: ✓ initialized (.dojops/)
│  Plans: 8 saved
│  Audit: 63 entries, chain intact
│
│  Toolchain:
│  ├  actionlint  ✓ v1.7.7
│  ├  hadolint    ✓ v2.12.0
│  ├  shellcheck  ✓ v0.10.0
│  └  terraform   ✗ not installed
│
└  System healthy

dojops doctor is an alias for dojops status. Both give the same output.

Step 14: Check for and install updates

Check if a newer version is available without installing:


dojops upgrade --check


┌  Update Check
│
│  Current: v1.1.6
│  Latest:  v1.1.6
│
└  Already up to date

When an update is available, install it:


dojops upgrade

For unattended updates in scripts:


dojops upgrade --yes

Try it yourself

Profile switching in a script. Write a shell script that generates a Kubernetes deployment using each of your configured profiles (production, staging, local-dev) and saves each output to a separate file. Compare the differences between providers.
Fallback stress test. Set your primary provider to a made-up API key so it fails, configure Ollama as the fallback, and run a generation. Watch the fallback trigger and confirm the output is still generated.
CI toolchain pre-population. Write a Makefile target called setup-toolchain that installs actionlint, hadolint, and shellcheck using dojops toolchain install. Run it in a fresh environment and verify all three tools are available before running dojops apply.

Troubleshooting

dojops provider add succeeds but the provider still shows “not configured”

Check that ~/.dojops/config.json is writable. If you installed DojOps globally with sudo npm install -g, the config directory may have incorrect permissions. Fix with sudo chown -R $USER ~/.dojops.

Profile switch doesn’t persist between terminal sessions

Profile state is stored in ~/.dojops/config.json. If you’re seeing the wrong profile, check whether an environment variable like DOJOPS_PROVIDER is overriding it — environment variables always win over config file settings.

Toolchain install fails with network errors

DojOps downloads toolchain binaries from GitHub Releases. If you’re behind a proxy, set HTTP_PROXY and HTTPS_PROXY before running the install. For air-gapped environments, download the binaries manually and copy them to ~/.dojops/toolchain/.

dojops status shows “chain broken” in the audit log

The audit chain breaks when entries are deleted or manually edited. Run dojops history repair to rebuild the chain pointers from the existing entries. Repair rebuilds pointers — it can’t recover deleted entries.

What you learned

Provider configuration in DojOps has three layers: the ~/.dojops/config.json file (written by CLI commands), environment variables (which override the config file), and per-command flags (which override both). Profiles snapshot the config file state and let you switch environments with one command — useful when you work across projects with different cost or latency requirements. The toolchain installs to an isolated directory so verification binaries don’t pollute your system PATH, and they auto-install on first use if you skip pre-installation.

Next steps

Getting Started — First-time setup from scratch
Provider Guide — Detailed per-provider configuration and model lists
Configuration Reference — Every config option documented
CLI Reference — Full provider, config, and toolchain command reference