diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..17135cb6
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,52 @@
+# =============================================================================
+# LLM Provider Configuration
+# =============================================================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# Then load before running:
+#   source .env && pnpm dev:console
+# =============================================================================
+
+# Default LLM provider (e.g., openai, anthropic, deepseek, kimi-coding, groq, mistral)
+export LLM_PROVIDER=
+
+# --- OpenAI ---
+export OPENAI_API_KEY=
+export OPENAI_BASE_URL=
+export OPENAI_MODEL=
+
+# --- Anthropic ---
+export ANTHROPIC_API_KEY=
+export ANTHROPIC_BASE_URL=
+export ANTHROPIC_MODEL=
+
+# --- DeepSeek ---
+export DEEPSEEK_API_KEY=
+export DEEPSEEK_BASE_URL=
+export DEEPSEEK_MODEL=
+
+# --- Kimi (Moonshot) ---
+export MOONSHOT_API_KEY=
+export MOONSHOT_BASE_URL=
+export MOONSHOT_MODEL=
+
+# --- Groq ---
+export GROQ_API_KEY=
+export GROQ_BASE_URL=
+export GROQ_MODEL=
+
+# --- Mistral ---
+export MISTRAL_API_KEY=
+export MISTRAL_BASE_URL=
+export MISTRAL_MODEL=
+
+# --- Together ---
+export TOGETHER_API_KEY=
+export TOGETHER_BASE_URL=
+export TOGETHER_MODEL=
+
+# --- Google ---
+export GOOGLE_API_KEY=
+export GOOGLE_BASE_URL=
+export GOOGLE_MODEL=
diff --git a/.gitignore b/.gitignore
index 118f0f6f..60d83b64 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,7 @@ release
 
 # env
 .env*
+!.env.example
 
 # platform specific
 *.dmg
diff --git a/README.md b/README.md
index e9294e9f..8cac46f3 100644
--- a/README.md
+++ b/README.md
@@ -33,9 +33,50 @@ skills/                 # Bundled skills (commit, code-review)
 
 ```bash
 pnpm install
-pnpm dev
 ```
 
+### Environment Configuration
+
+The Agent requires LLM provider credentials. Copy the example and fill in your values:
+
+```bash
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+Example `.env` for OpenAI:
+
+```bash
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
+export OPENAI_BASE_URL=https://api.openai.com/v1
+export OPENAI_MODEL=gpt-4o
+```
+
+Load the environment before starting services that use the Agent:
+
+```bash
+# Hub Console (requires LLM env vars)
+source .env && pnpm dev:console
+
+# Agent CLI
+source .env && pnpm agent:cli "hello"
+
+# Gateway (no LLM env vars needed)
+pnpm dev:gateway
+```
+
+See `.env.example` for all supported providers (OpenAI, Anthropic, DeepSeek, Kimi, Groq, Mistral, etc.).
+
+### Configuration Priority
+
+Each setting is resolved in order (first match wins):
+
+1. **CLI argument** — `--provider`, `--model`, `--api-key`, `--base-url`
+2. **Environment variable** — `LLM_PROVIDER`, `OPENAI_MODEL`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, etc.
+3. **Session metadata** — restored from previous session
+4. **Default** — `kimi-coding` provider with `kimi-k2-thinking` model
+
 ## Agent CLI
 
 Use the agent module directly from the CLI for isolated testing.