From 538c181cd62024d4d069f683375a90909e15f217 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 16:26:32 -0700 Subject: [PATCH] docs(cookbook): set a master key before the gollem and mock prompt guides start the proxy --- cookbook/gollem_go_agent_framework/README.md | 29 +++++++++++++++++-- .../gollem_go_agent_framework/basic/main.go | 4 ++- .../streaming/main.go | 6 ++-- .../gollem_go_agent_framework/tools/main.go | 6 ++-- .../mock_prompt_management_server/README.md | 7 +++++ 5 files changed, 45 insertions(+), 7 deletions(-) diff --git a/cookbook/gollem_go_agent_framework/README.md b/cookbook/gollem_go_agent_framework/README.md index 729f985d086..2543edd73ac 100644 --- a/cookbook/gollem_go_agent_framework/README.md +++ b/cookbook/gollem_go_agent_framework/README.md @@ -6,7 +6,13 @@ A working example showing how to use [gollem](https://github.com/fugue-labs/goll ### 1. Start LiteLLM Proxy +The proxy refuses to start without a master key, so generate one first and keep it for step 2: + ```bash +export OPENAI_API_KEY="sk-..." +export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" +echo "$LITELLM_MASTER_KEY" + # Simple start with a single model litellm --model gpt-4o @@ -16,7 +22,11 @@ litellm --config proxy_config.yaml ### 2. Run the examples +In a second terminal, give the examples the master key from step 1. They send `LITELLM_API_KEY` to the proxy as their API key: + ```bash +export LITELLM_API_KEY="" + # Install Go dependencies go mod tidy @@ -48,6 +58,7 @@ model := openai.NewLiteLLM("http://localhost:4000", openai.WithModel("gpt-4o"), // OpenAI // openai.WithModel("claude-sonnet"), // Anthropic // openai.WithModel("gemini-pro"), // Google + openai.WithAPIKey(os.Getenv("LITELLM_API_KEY")), ) ``` @@ -89,23 +100,37 @@ Go App (gollem) → LiteLLM Proxy → OpenAI / Anthropic / Google / ... ## Environment Variables ```bash -# Required for providers you want to use (set in LiteLLM config or env) +# Proxy terminal: keys for the providers you want to use (set in LiteLLM config or env) export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." +# Proxy terminal: required, the proxy refuses to start without a master key +export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" + +# Go terminal: the key the examples send to the proxy (the master key or a virtual key) +export LITELLM_API_KEY="" + # Optional: point to a non-default LiteLLM proxy export LITELLM_PROXY_URL="http://localhost:4000" ``` +When `LITELLM_API_KEY` is unset, gollem falls back to sending `OPENAI_API_KEY`, which the proxy rejects unless it holds a LiteLLM key. + ## Troubleshooting +**Proxy refuses to start with `no master key is set`?** +- Export `LITELLM_MASTER_KEY` before starting it, as in step 1 + **Connection errors?** - Make sure LiteLLM is running: `litellm --model gpt-4o` - Check the URL is correct (default: `http://localhost:4000`) +**Authentication errors (401, or 400 `No connected db.`)?** +- Set `LITELLM_API_KEY` in the Go terminal to the proxy's master key + **Model not found?** - Verify the model name matches what's configured in LiteLLM -- Run `curl http://localhost:4000/models` to see available models +- Run `curl http://localhost:4000/models -H "Authorization: Bearer $LITELLM_API_KEY"` to see available models **Tool calls not working?** - Ensure the underlying model supports tool use (GPT-4o, Claude, Gemini) diff --git a/cookbook/gollem_go_agent_framework/basic/main.go b/cookbook/gollem_go_agent_framework/basic/main.go index 838149a8ff9..a596c13775c 100644 --- a/cookbook/gollem_go_agent_framework/basic/main.go +++ b/cookbook/gollem_go_agent_framework/basic/main.go @@ -2,8 +2,9 @@ // // Usage: // +// export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" // litellm --model gpt-4o # start proxy in another terminal -// go run ./basic +// LITELLM_API_KEY="" go run ./basic package main import ( @@ -26,6 +27,7 @@ func main() { // provider pointed at the given URL. model := openai.NewLiteLLM(proxyURL, openai.WithModel("gpt-4o"), // any model name configured in LiteLLM + openai.WithAPIKey(os.Getenv("LITELLM_API_KEY")), ) // Create and run a simple agent. diff --git a/cookbook/gollem_go_agent_framework/streaming/main.go b/cookbook/gollem_go_agent_framework/streaming/main.go index 42bc9bbe34a..632b1a8812b 100644 --- a/cookbook/gollem_go_agent_framework/streaming/main.go +++ b/cookbook/gollem_go_agent_framework/streaming/main.go @@ -5,8 +5,9 @@ // // Usage: // -// litellm --model gpt-4o -// go run ./streaming +// export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" +// litellm --model gpt-4o # start proxy in another terminal +// LITELLM_API_KEY="" go run ./streaming package main import ( @@ -27,6 +28,7 @@ func main() { model := openai.NewLiteLLM(proxyURL, openai.WithModel("gpt-4o"), + openai.WithAPIKey(os.Getenv("LITELLM_API_KEY")), ) agent := core.NewAgent[string](model) diff --git a/cookbook/gollem_go_agent_framework/tools/main.go b/cookbook/gollem_go_agent_framework/tools/main.go index ed41a95ffef..0de5cc2cd19 100644 --- a/cookbook/gollem_go_agent_framework/tools/main.go +++ b/cookbook/gollem_go_agent_framework/tools/main.go @@ -6,8 +6,9 @@ // // Usage: // -// litellm --model gpt-4o -// go run ./tools +// export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" +// litellm --model gpt-4o # start proxy in another terminal +// LITELLM_API_KEY="" go run ./tools package main import ( @@ -35,6 +36,7 @@ func main() { model := openai.NewLiteLLM(proxyURL, openai.WithModel("gpt-4o"), + openai.WithAPIKey(os.Getenv("LITELLM_API_KEY")), ) // Define a type-safe tool. The function signature enforces correct types. diff --git a/cookbook/mock_prompt_management_server/README.md b/cookbook/mock_prompt_management_server/README.md index c13061cfe89..d1ab33555d6 100644 --- a/cookbook/mock_prompt_management_server/README.md +++ b/cookbook/mock_prompt_management_server/README.md @@ -60,12 +60,19 @@ prompts: ### Start LiteLLM Proxy +The proxy refuses to start without a master key, so generate one first: + ```bash +export OPENAI_API_KEY="sk-..." +export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" +echo "$LITELLM_MASTER_KEY" litellm --config config.yaml ``` ### Make a Request +In another terminal, export the same `LITELLM_MASTER_KEY` printed above, then send the request: + ```bash curl http://0.0.0.0:4000/v1/chat/completions \ -H "Content-Type: application/json" \