Environment Variables

MAGIC Data Agent Skills uses environment variables for authentication and configuration. None are required for basic use — they unlock specific capabilities like database connections, HuggingFace access, and LLM-powered synthesis.

Reference

Variable	Used By	Required	Description
`HF_TOKEN`	magic-data-loading	For private datasets	HuggingFace Hub authentication token
`HUGGING_FACE_HUB_TOKEN`	magic-data-loading	Alternative	Alias for `HF_TOKEN` (legacy name, both work)
`DATABASE_URL`	magic-data-loading, `/magic:connect`	For database tasks	SQLAlchemy connection string
`MAGIC_LLM_MODEL`	magic-data-synthesis	For synthesis	LLM model name override
`MAGIC_LLM_BASE_URL`	magic-data-synthesis	For synthesis	LLM API base URL (for local models or custom endpoints)
`MAGIC_LLM_API_KEY`	magic-data-synthesis	For synthesis	LLM API key
`MAGIC_LLM_MAX_TOKENS`	magic-data-synthesis	Optional	Maximum tokens per generation call
`MPLBACKEND`	magic-data-visualization	Recommended	Set to `Agg` for headless environments (CI, servers)
`GOOGLE_API_KEY`	magic-workspace-init	Optional	Google Gemini API access for synthesis

Setup

Copy .env.example to .env in your project root and fill in the values you need:

cp .env.example .env

Never commit your .env file. It is listed in .gitignore by default.

Variable Details

HF_TOKEN

Required to access private or gated HuggingFace Hub datasets. Public datasets work without a token.

export HF_TOKEN="hf_your_token_here"

Get your token at huggingface.co/settings/tokens. Set read scope for downloading datasets; set write scope if you also need to push with /magic:deliver.

Token resolution order in loading scripts:

Explicit --token-env flag value
HF_TOKEN env var
HUGGING_FACE_HUB_TOKEN env var (legacy)
Cached CLI login (huggingface-cli login)

DATABASE_URL

SQLAlchemy connection string for /magic:connect and database loading tasks.

# PostgreSQL
export DATABASE_URL="postgresql://user:password@host:5432/dbname"

# MySQL
export DATABASE_URL="mysql+pymysql://user:password@host:3306/dbname"

# SQLite
export DATABASE_URL="sqlite:///path/to/database.db"

Database connections are read-only by default. Write access for /magic:deliver requires explicit confirmation.

MAGIC_LLM_* Variables

Configure the LLM provider for magic-data-synthesis. These override the default model selection in DataDesigner:

# Use a specific model
export MAGIC_LLM_MODEL="claude-sonnet-4-6"

# Use a local model via Ollama
export MAGIC_LLM_BASE_URL="http://localhost:11434/v1"
export MAGIC_LLM_MODEL="llama3.2"
export MAGIC_LLM_API_KEY="ollama"

# Limit token usage per call
export MAGIC_LLM_MAX_TOKENS="2048"

MPLBACKEND

Set to Agg in any environment without a display server (CI pipelines, servers, Docker containers). Without this, matplotlib chart generation fails with a display error.

export MPLBACKEND="Agg"

This is automatically set by the test suite (MPLBACKEND=Agg pytest ...). For production use, add it to your shell profile or .env.

Setting Variables Persistently

Add to your shell profile for persistence across sessions:

# ~/.zshrc or ~/.bashrc
export HF_TOKEN="hf_your_token_here"
export MPLBACKEND="Agg"

Or use a .env file in your project root (loaded automatically by most AI coding tools and the MAGIC workspace init process).

Was this page helpful?

On this page