SHIPIT

Environment setup

2 min read
6 sections
Edit this page

SHIPIT Agent uses environment variables for provider selection, credentials, and runtime knobs. Everything loads automatically from a .env file walking upward from your current working directory — so the same notebook, script, or CLI works regardless of where you run it from.

The same agent code runs on every provider — OpenAI, Anthropic, Bedrock, Vertex, Gemini, Groq, Together, Ollama, and LiteLLM. Set SHIPIT_LLM_PROVIDER plus that provider's credentials and build_llm_from_env() does the rest. For per-provider init snippets (direct adapter class and env-var setup), see LLM providers — use any model.

Minimal .env

bash
SHIPIT_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

Full .env.example

bash
# Core agent settings
SHIPIT_LLM_PROVIDER=bedrock           # bedrock|openai|anthropic|gemini|vertex|groq|together|ollama|litellm
SHIPIT_AGENT_PROMPT=You are a decisive engineering agent.
SHIPIT_STREAM=0
SHIPIT_SESSION_ID=demo-session
SHIPIT_TRACE_ID=demo-trace
SHIPIT_WORKSPACE_ROOT=.shipit_workspace

# Web search
SHIPIT_WEB_SEARCH_PROVIDER=duckduckgo
BRAVE_SEARCH_API_KEY=
SERPER_API_KEY=
TAVILY_API_KEY=

# OpenAI
SHIPIT_OPENAI_MODEL=gpt-4o-mini
SHIPIT_OPENAI_TOOL_CHOICE=            # "required" forces at least one tool call per turn
OPENAI_API_KEY=

# Anthropic
SHIPIT_ANTHROPIC_MODEL=claude-opus-4-1
ANTHROPIC_API_KEY=

# AWS Bedrock via LiteLLM
SHIPIT_BEDROCK_MODEL=bedrock/openai.gpt-oss-120b-1:0
AWS_REGION_NAME=us-east-1
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_SESSION_TOKEN=
AWS_PROFILE=

# Google Gemini
SHIPIT_GEMINI_MODEL=gemini/gemini-1.5-pro
GEMINI_API_KEY=                       # or GOOGLE_API_KEY

# Google Vertex AI
SHIPIT_VERTEX_MODEL=vertex_ai/gemini-1.5-pro
GOOGLE_APPLICATION_CREDENTIALS=       # or SHIPIT_VERTEX_CREDENTIALS_FILE
VERTEXAI_PROJECT=                     # or GOOGLE_CLOUD_PROJECT
VERTEXAI_LOCATION=                    # or VERTEX_LOCATION / GOOGLE_CLOUD_LOCATION

# Groq
SHIPIT_GROQ_MODEL=groq/llama-3.3-70b-versatile
GROQ_API_KEY=

# Together AI
SHIPIT_TOGETHER_MODEL=together_ai/meta-llama/Llama-3.1-70B-Instruct-Turbo
TOGETHERAI_API_KEY=                   # or TOGETHER_API_KEY

# Ollama (local server, no API key)
SHIPIT_OLLAMA_MODEL=ollama/llama3.1

# LiteLLM (proxy to ~everything)
SHIPIT_LITELLM_MODEL=                 # required when SHIPIT_LLM_PROVIDER=litellm
SHIPIT_LITELLM_API_KEY=
SHIPIT_LITELLM_API_BASE=              # set this → LiteLLMProxyChatLLM
SHIPIT_LITELLM_CUSTOM_PROVIDER=

How .env is discovered

build_llm_from_env() walks upward from the current working directory looking for the first .env file it finds. That means:

CWD.env locationWorks?
/path/to/project//path/to/project/.env✅
/path/to/project/notebooks//path/to/project/.env✅ (walks up)
/path/to/project/deep/nested/dir//path/to/project/.env✅ (walks up)
/tmp/scratch/(none)❌ — raises "Missing environment variable"

Existing shell environment variables always take precedence over .env — .env only fills in missing values, it never overrides.

Provider credential requirements

ProviderRequired env vars
openaiOPENAI_API_KEY
anthropicANTHROPIC_API_KEY
bedrockAWS_REGION_NAME (or AWS_DEFAULT_REGION) + one of AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY, AWS_PROFILE, or instance role
vertexcreds file (GOOGLE_APPLICATION_CREDENTIALS or SHIPIT_VERTEX_CREDENTIALS_FILE) + project (VERTEXAI_PROJECT or GOOGLE_CLOUD_PROJECT) + location (VERTEXAI_LOCATION / VERTEX_LOCATION / GOOGLE_CLOUD_LOCATION)
geminiGEMINI_API_KEY or GOOGLE_API_KEY
groqGROQ_API_KEY
togetherTOGETHERAI_API_KEY or TOGETHER_API_KEY
ollamaNone (requires local Ollama server running)
litellmSHIPIT_LITELLM_MODEL (+ the upstream provider's creds, or SHIPIT_LITELLM_API_BASE for a proxy)

See LLM providers — use any model for the exact adapter class and init snippet for each.

If any required var is missing, build_llm_from_env('openai') raises:

bash
RuntimeError: Missing environment variable for openai. Set one of: OPENAI_API_KEY

Switching providers without restarting

python
from shipit_agent.llms import build_llm_from_env

# Explicit override (ignores SHIPIT_LLM_PROVIDER):
llm_openai = build_llm_from_env('openai')
llm_bedrock = build_llm_from_env('bedrock')

# Uses SHIPIT_LLM_PROVIDER from .env (defaults to 'bedrock' if unset):
llm = build_llm_from_env()

Security notes

  • Never commit .env. The shipped .gitignore already excludes .env, .env.local, and .env.*.local.
  • Use .env.example as a template. Commit it with all values blank so contributors know which vars to set.
  • The credential visibility printer in the sample notebooks never prints the actual value — only ✓ set / ✗ missing. Safe to share.
  • API keys are never written to logs or events. Adapters only report the provider name and model on LLMResponse.metadata.