Configuring Providers, Models, and Permissions

Configuration scope: what OpenCode needs to know

OpenCode needs to know four things to start up safely:

1. Which LLM provider and model — Anthropic's Claude, OpenAI's GPT, local Ollama, a self-hosted vLLM instance, etc.
2. How to authenticate — API keys, local endpoints, credentials for your chosen provider.
3. What it's allowed to do — which directories it can read and modify, which commands it can execute, whether it can access the internet.
4. How to behave — max tokens per request, max turns in the agent loop, whether to run in plan mode or build mode by default.

Each of these is a lever for safety and control. Getting them right means the agent does useful work without doing harmful work.

Core provider configuration

The most basic configuration selects your model provider. Here are common patterns:

For Anthropic's Claude:

OPENCODE_PROVIDER=anthropic
OPENCODE_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_API_KEY=${your_api_key}

For OpenAI:

OPENCODE_PROVIDER=openai
OPENCODE_MODEL=gpt-4-turbo
OPENAI_API_KEY=${your_api_key}

For local Ollama (running on your machine):

OPENCODE_PROVIDER=ollama
OPENCODE_MODEL=llama2-13b
OLLAMA_BASE_URL=http://localhost:11434

For self-hosted vLLM:

OPENCODE_PROVIDER=vllm
OPENCODE_MODEL=meta-llama/Llama-2-13b-hf
VLLM_BASE_URL=http://your-vllm-server:8000

Each provider requires different authentication. Anthropic and OpenAI use API keys (which you shouldn't commit to git—use environment variables). Local or self-hosted providers often just need an HTTP endpoint and no authentication.

Permission boundaries: what the agent can touch

The most important safety lever is defining what the agent is allowed to touch. OpenCode supports several permission modes:

Directory whitelist. Tell OpenCode which directories it can read and modify. For example:

OPENCODE_ALLOWED_DIRS=/home/user/myproject/src,/home/user/myproject/tests
OPENCODE_FORBIDDEN_DIRS=/home/user/myproject/.env,/home/user/myproject/secrets

The agent can read and modify code in src/ and tests/, but it cannot touch anything in .env or secrets/. This prevents the agent from accidentally exposing secrets or modifying sensitive configuration.

Command execution whitelist. The agent needs to run commands (tests, linters, builds). You can restrict which commands are allowed:

OPENCODE_ALLOWED_COMMANDS=npm test,npm run build,npm run lint,git status
OPENCODE_FORBIDDEN_COMMANDS=rm,dd,curl,git push

The agent can run tests and linters, but it cannot delete files, access the network, or push changes to a remote repository.

Read-only mode. For high-risk scenarios or for training/auditing:

OPENCODE_READ_ONLY=true

The agent can read your codebase, analyze it, and output plans, but it cannot modify files or run commands. Use this when you're first setting up OpenCode and want to see what it would do without letting it do anything yet.

A worked example: safe configuration for a CI/CD agent

Say you want to run OpenCode in your CI pipeline to automatically fix linting issues. Here's a conservative configuration:

OPENCODE_PROVIDER=anthropic
OPENCODE_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}  # Injected by your CI system

# Only allow modifying code and tests
OPENCODE_ALLOWED_DIRS=./src,./tests,./public

# Don't let it touch config or infra
OPENCODE_FORBIDDEN_DIRS=./config,./infra,.env,./secrets

# Only allow safe commands
OPENCODE_ALLOWED_COMMANDS=npm run lint,npm run lint:fix,npm test,git status,git diff

# Don't allow pushing or deleting
OPENCODE_FORBIDDEN_COMMANDS=rm,git push,git commit,curl,wget

# Default to plan mode for visibility
OPENCODE_DEFAULT_MODE=plan

# Conservative iteration limit
OPENCODE_MAX_TURNS=5

# Stop if the agent gets confused
OPENCODE_ERROR_THRESHOLD=2

With this config, the agent can read your source code, analyze linting issues, and propose fixes. It can run linters and tests to validate its changes. But it cannot push changes to the repository (a human has to review the plan first), cannot access secrets, and cannot run arbitrary commands.

Authentication patterns: balancing security and convenience

Different providers have different authentication stories:

Cloud API providers (Anthropic, OpenAI). You need an API key. Never commit this to git. Instead:

• Store it in a .env file (which you .gitignore)
• Inject it as an environment variable in CI/CD systems
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) in production

Local providers (Ollama, local vLLM). Usually no authentication needed—just a URL. Safe to commit to config (they're running on your local machine or private network).

Self-hosted cloud (vLLM on EC2, etc.). If your self-hosted instance requires authentication, treat it like a cloud API provider—use environment variables for credentials.

Token budgets and cost control

Coding tasks can involve large context windows (your entire codebase as context), and large numbers of model calls (reasoning about a change, running tests, iterating). This can get expensive fast. Control it with:

OPENCODE_MAX_TOKENS_PER_REQUEST=8192
OPENCODE_MAX_TURNS=10
OPENCODE_MAX_COST_PER_TASK=5.00  # Stop if the agent has spent more than $5

For Anthropic's Claude, you can also use prompt caching (if configured) to reduce cost on repeated context:

OPENCODE_USE_CACHE=true

The agent will use the same system prompt and frequently-needed context (like your codebase structure) across multiple model calls, reducing token count.

Mode defaults and overrides

You can set a default mode for how OpenCode operates:

OPENCODE_DEFAULT_MODE=build  # Default to direct modification

But allow overrides at runtime:

opencode --mode=plan "add pagination to the user list"

This gives you flexibility: fast builds most of the time, but the ability to switch to plan mode when the task is risky.

Common mistake

Over-configuring permissions out of fear. A configuration so restrictive that the agent can't actually do anything useful defeats the purpose. Start with a reasonable boundary (the agent can modify source and test code, can't touch infra or secrets, can only run tests and linters), run it a few times to build confidence, then relax constraints if it proves safe. Configuration is not a one-time setup—it should evolve as you learn how OpenCode works in your context.