Set Up a Model

Every agent needs a model to think with. Bring an API key for a cloud provider, or run a model locally with Docker Model Runner. This page walks through both paths end to end.

Pick a Path

You can set up both. When you don't name a model, Docker Agent's auto selection picks the first cloud provider with a configured key and falls back to a locally pulled Docker Model Runner model.

Path A: Cloud Provider (API Key)

1. Get an API key

Create a key in your provider's console:

Every other provider works the same way. See Model Providers for the full list and each provider's environment variable.

2. Store the key

The fastest option is an environment variable in your shell:

$ export ANTHROPIC_API_KEY=sk-ant-...

That lasts for the current shell session. To set a key up once, use any other built-in secret source:

# Env file, passed at run time
$ echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
$ docker agent run --env-from-file .env

# pass password manager (Linux, macOS)
$ pass insert ANTHROPIC_API_KEY

# macOS Keychain
$ security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w

The entry name must match the environment variable the provider expects. Managing Secrets covers every source (Docker Compose secrets, credential helpers, 1Password references) and the order they are checked in.

3. Verify

docker agent doctor shows whether the key is visible and where it comes from:

$ docker agent doctor

Model provider credentials
  PROVIDER    STATUS    CREDENTIAL          SOURCE
  anthropic   found     ANTHROPIC_API_KEY   environment
  openai      not set   OPENAI_API_KEY      -
  ...

Docker Model Runner
  Status: not installed (https://docs.docker.com/ai/model-runner/get-started/)

Model auto-selection
  auto -> anthropic/claude-sonnet-4-6

No issues found.

4. Run

$ docker agent run

With no config file, the default agent picks the provider you configured. To name a model explicitly, use --model or the model field in your config:

$ docker agent run --model anthropic/claude-sonnet-4-5

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A helpful coding assistant
    instruction: You are an expert software developer.

Path B: Local Model (Docker Model Runner)

Docker Model Runner (DMR) runs open models on your own machine: no API key, no per-token cost, and prompts never leave your computer.

1. Install Docker Model Runner

Model Runner ships with Docker Desktop (enable it under Settings > AI) and is also available for Docker Engine. Check that it responds:

$ docker model status

If the command is missing or fails, follow the Model Runner get-started guide.

2. Pull a model

$ docker model pull ai/qwen3

ai/qwen3 is the model Docker Agent reaches for by default, but any model from the Docker Hub ai catalog works. Pick one sized for your machine's memory. List what you have locally:

$ docker model ls

3. Verify

$ docker agent doctor

Model provider credentials
  PROVIDER    STATUS    CREDENTIAL          SOURCE
  anthropic   not set   ANTHROPIC_API_KEY   -
  ...

Docker Model Runner
  Status: reachable, 1 model(s) pulled:
    - ai/qwen3:latest

Model auto-selection
  auto -> dmr/ai/qwen3:latest

No issues found.

4. Run

$ docker agent run --model dmr/ai/qwen3

Or in your config:

agents:
  root:
    model: dmr/ai/qwen3
    description: A local assistant
    instruction: You are a helpful assistant.

When no cloud key is configured, bare docker agent run auto-selects a pulled local model, so after docker model pull you can run with no flags at all. The Docker Model Runner provider page covers context size, runtime flags, and other tuning options.

Check Your Setup Anytime

docker agent doctor reports which providers have credentials (and from which source), whether Docker Model Runner is reachable and which models are pulled, and which model auto would pick. Secret values are never printed.

$ docker agent doctor                     # credential, DMR, and auto-selection state
$ docker agent doctor ./agent.yaml        # also check that file's requirements

It exits non-zero when something would block a run, which makes it usable as a CI preflight. See the CLI reference.

What's Next?

• Quick Start — run your first agent now that a model is available.
• Models — inline vs. named models, fallbacks, and auto selection.
• Managing Secrets — every way to store credentials, compared.
• Troubleshooting — decode "no model available" and credential errors.