Section 3: Configuration & API Keys¶

Welcome to Section 3 of the OSA FAQ! This section covers everything you need to know about configuring OSA, setting up API keys, and managing tokens for seamless operation.

3.1 What tokens/API keys do I need?¶

OSA requires different tokens depending on your use case. Here's a complete overview:

Token Name	Description	Mandatory	When Required
`GIT_TOKEN`	Personal GitHub/GitLab/Gitverse token for cloning repos, accessing metadata, and creating PRs	✅ Yes*	Always, unless using `--no-fork` with public repos
`HOST_LLM_COMMAND`	Logged-in Codex CLI command for the default subscription-backed provider (`codex`)	❌ No	When using default `--api host` command transport
`HOST_LLM_BRIDGE_DIR`	Directory for Host LLM request/response JSON files	❌ No	When using default `--api host` bridge transport
`HOST_LLM_REQUEST_TIMEOUT_SECONDS`	Host LLM request timeout	❌ No	Optional for long host-backed runs
`OPENAI_API_KEY`	API key for OpenAI, VseGPT, OpenRouter providers	❌ No	When using `--api openai` or compatible providers
`ITMO_MODEL_URL`	URL for ITMO-hosted LLM endpoint	❌ No	When using ITMO's internal model

* GIT_TOKEN can be omitted if you use --no-fork and work only with public repositories in read-only mode.

Token Alternatives:

# Instead of GIT_TOKEN, you can use platform-specific tokens:
GITHUB_TOKEN=<your_github_token>    # For GitHub
GITLAB_TOKEN=<your_gitlab_token>    # For GitLab
GITVERSE_TOKEN=<your_gitverse_token> # For Gitverse

Minimum Setup for Testing:

# Default Host LLM provider; no OpenAI-compatible API key needed:
export HOST_LLM_COMMAND=codex
export GIT_TOKEN=your_token

3.2 How do I set up OPENAI_API_KEY?¶

Setting up your OpenAI API key is straightforward.

Step 1: Get Your API Key

Go to OpenAI Platform
Sign in or create an account
Click "Create new secret key"
Copy the key (it starts with sk-)

Step 2: Set the Environment Variable

Platform	Command
Linux/macOS (bash/zsh)	`export OPENAI_API_KEY="sk-..."`
Windows (PowerShell)	`setx OPENAI_API_KEY "sk-..."`
Windows (CMD)	`set OPENAI_API_KEY=sk-...`

Step 3: Verify It Works

# Check if variable is set
echo $OPENAI_API_KEY  # Linux/macOS
echo %OPENAI_API_KEY%  # Windows CMD

# Test with OSA
python -m osa_tool.run -r https://github.com/username/repo --api openai --model gpt-4

Using in .env File (Recommended):

# Create or edit .env in your project root
echo "OPENAI_API_KEY=sk-..." >> .env

Security Best Practices:

✅ Do	❌ Don't
Store keys in `.env` (added to `.gitignore`)	Hardcode keys in scripts or commits
Use environment-specific keys	Share keys in public repositories
Rotate keys periodically	Use organization keys for personal projects
Limit key permissions in OpenAI dashboard	Grant unnecessary permissions

Troubleshooting:

Issue	Solution
"Invalid API key" error	Verify key format, check OpenAI dashboard for key status
"Rate limit exceeded"	Upgrade plan or reduce request frequency

3.3 How do I set up GIT_TOKEN?¶

A Git token enables OSA to interact with your repositories (clone, create branches, open PRs).

For GitHub:

Go to GitHub Settings → Developer settings → Personal access tokens
Click "Generate new token (classic)" or "Fine-grained token"
Select scopes:
✅ repo (Full control of private repositories)
✅ workflow (Update GitHub Actions workflows)
✅ write:packages (if publishing to GitHub Packages)
Generate and copy the token (starts with ghp_)

For GitLab:

Go to GitLab Settings → Access Tokens
Name your token, set expiration
Select scopes:
✅ api (Full API access)
✅ write_repository (Clone/push code)
Create and copy the token

Set the Environment Variable:

# Linux/macOS
export GIT_TOKEN="ghp_..."

# Windows PowerShell
setx GIT_TOKEN "ghp_..."

# Or add to .env file
echo "GIT_TOKEN=ghp_..." >> .env

Token Permissions Reference:

Action	Required Scope
Clone public repo	None (token optional)
Clone private repo	`repo` (GitHub) / `read_repository` (GitLab)
Create branch/commit	`repo` / `write_repository`
Create Pull Request	`repo` / `write_repository`
Update CI/CD workflows	`workflow` (GitHub) / `api` (GitLab)

Using Platform-Specific Tokens:

# GitHub
export GITHUB_TOKEN="ghp_..."

# GitLab  
export GITLAB_TOKEN="glpat-..."

# Gitverse
export GITVERSE_TOKEN="gv_..."

Troubleshooting Git Token Issues:

Issue	Solution
"403 Forbidden"	Check token scopes, ensure repo access
"Authentication failed"	Verify token is current, not expired
"Rate limit exceeded"	Use fine-grained tokens, implement retry logic
Token not working with fork	Ensure token has `repo` scope for fork creation

3.4 Which LLM providers are supported?¶

OSA supports the subscription-backed Host LLM provider directly, any OpenAI-compatible API, GigaChat, a local Ollama server, and a self-hosted REST endpoint.

Supported Providers and Configuration:

Provider	API Type	Models Available	Cost	Best For	--api Value	--base-url	Auth Variable	Example Model
Host LLM	Subscription-backed host command or bridge	GPT-5.6 Luna and compatible subscription models	Subscription	Default OSA runs without an API key	host	Ignored	HOST_LLM_COMMAND or HOST_LLM_BRIDGE_DIR	gpt-5.6-luna
OpenAI	OpenAI-compatible	gpt-4, gpt-3.5-turbo, gpt-4o	💰 Paid	High-quality, reliable results	openai	https://api.openai.com/v1	OPENAI_API_KEY	gpt-4o
OpenRouter	OpenAI-compatible	100+ models (Claude, Llama, Mistral)	💰/🆓 Mixed	Flexibility, cost optimization	openai	https://openrouter.ai/api/v1	OPENAI_API_KEY	qwen/qwen3-30b
VseGPT	OpenAI-compatible	OpenAI models via Russian proxy	💰 Paid	Users in Russia/CIS region	openai	https://api.vsegpt.ru/v1	OPENAI_API_KEY	openai/gpt-3.5-turbo
Ollama	Local/Ollama API	Llama 3, Gemma, Mistral, custom	🆓 Free	Privacy, offline use, customization	ollama	http://localhost:11434	None	gemma3:27b
ITMO Hosted	OpenAI-compatible	ITMO fine-tuned models	🆓 Free*	Research, testing, ITMO community	openai	https://osa.nsslab.onti.actcognitive.org/api/v1	None (or ITMO_API_KEY)	itmo-research
Gigachat	Native API	GigaChat models by Sber	💰 Paid	Russian language, local compliance	openai	https://gigachat.devices.sberbank.ru/api/v1	AUTHORIZATION_KEY	GigaChat

3.5 How do I configure different LLM providers?¶

OSA autodetects provider from base url, but you can manually configure it with the following options:

Manual configuration varies slightly by provider. Here are complete examples for each:

Host LLM (Default):

# Use the logged-in Codex CLI command
export HOST_LLM_COMMAND=codex

python -m osa_tool.run \
  -r https://github.com/username/repo

# Or choose the provider/model explicitly
python -m osa_tool.run \
  -r https://github.com/username/repo \
  --api host \
  --model gpt-5.6-luna

For bridge-based host execution, set HOST_LLM_BRIDGE_DIR instead of HOST_LLM_COMMAND. The bridge request includes max_tokens, temperature, and top_p; the Codex command transport rejects custom generation controls because that CLI protocol does not expose them.

OpenAI:

# Set environment variables
export OPENAI_API_KEY="sk-..."

# Run OSA
python -m osa_tool.run \
  -r https://github.com/username/repo \
  --api openai \
  --model gpt-4o \
  --base-url https://api.openai.com/v1

OpenRouter:

# OpenRouter uses OpenAI-compatible API
export OPENAI_API_KEY="sk-or-..."  # Your OpenRouter key

python -m osa_tool.run \
  -r https://github.com/username/repo \
  --api openai \
  --base-url https://openrouter.ai/api/v1 \
  --model qwen/qwen3-30b-a3b-instruct-2507

VseGPT:

export OPENAI_API_KEY="your-vsegpt-key"

python -m osa_tool.run \
  -r https://github.com/username/repo \
  --api openai \
  --base-url https://api.vsegpt.ru/v1 \
  --model openai/gpt-3.5-turbo

Ollama (Local):

# First, pull your model locally
ollama pull gemma3:27b

# Run OSA pointing to local Ollama instance
python -m osa_tool.run \
  -r https://github.com/username/repo \
  --api ollama \
  --base-url http://localhost:11434 \
  --model gemma3:27b

3.6 Can I use local LLM models?¶

Yes! OSA fully supports local LLM models via Ollama or self-hosted OpenAI-compatible servers.

3.7 How do I use the ITMO hosted model?¶

ITMO University provides a hosted OSA endpoint for research and testing purposes.

Access Options:

Option	Description	How to Use
Public Web GUI	No installation, browser-based	Visit osa.nsslab.onti.actcognitive.org
Community Access	For ITMO students/researchers	Contact ITMO OpenSource team for credentials

3.8 What configuration options are available?¶

OSA offers extensive CLI configuration options. For the complete reference visit the README.md.

3.9 How do I use custom TOML configuration?¶

OSA supports custom configuration via TOML files for complex setups and reproducibility.

Creating a TOML Configuration File:

You can find the actual config file config.toml.

A custom file only needs the keys you want to change. It is merged over the default config.toml section by section, so any key you leave out keeps its default value. List values (for example translate_readme) replace the default list instead of being appended to it:

[general]
translate_readme = ["Russian"]
artefacts_language = "Russian"

[llm]
model = "gpt-5.6-luna"

Precedence: explicit CLI flags > custom --config-file > default config.toml.

Using the Configuration File:

# Run OSA with custom config
python -m osa_tool.run --config-file config.toml

# Override specific values via CLI (CLI takes precedence)
python -m osa_tool.run \
  --config-file config.toml \
  --model gpt-5.6-luna \  # Overrides [llm].model
  --temperature 0.2      # Overrides [llm].temperature