Environment Configuration

Configure environment variables for your agents using .env files with AgentVisor™.

Overview

AgentVisor supports Python-style .env files to configure environment variables for agents. This is useful for:

API Keys: Pass secrets like OPENAI_API_KEY without hardcoding
Configuration: Set runtime options like LOG_LEVEL or DATABASE_URL
Development: Use different configs for dev/staging/production

Environment variables are securely transmitted from the host to the guest sandbox, ensuring they never appear in container metadata or process listings.

Basic Usage

Auto-Discovery

If a .env file exists in your agent directory, AgentVisor automatically discovers and loads it:

my-agent/
├── agent.py
├── langgraph.json
└── .env           # Auto-discovered

# .env is automatically loaded
agentvisor run ./my-agent --sandbox=none

The CLI prints a confirmation message when auto-discovery finds a file:

Found .env file: /path/to/my-agent/.env

note

Auto-discovery applies to agentvisor run and agentvisor serve. For built images deployed with agentvisor build, see Production: Built Images below.

Explicit Path

You can specify an explicit .env file path:

agentvisor run ./my-agent \
    --sandbox=none \
    --env-files=/path/to/secrets.env

Or multiple files (later files override earlier):

agentvisor run ./my-agent \
    --sandbox=none \
    --env-files=base.env,secrets.env

This is useful when:

Your .env file is outside the agent directory
You want to use different config files for different environments
You're sharing a config file across multiple agents
You need to layer environment variables (base + environment-specific)

File Format

The .env file uses standard format:

# my-agent/.env

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Database
DATABASE_URL=postgres://user:pass@host:5432/db

# Configuration
LOG_LEVEL=debug
MAX_RETRIES=3

# Quoted values (preserves whitespace)
GREETING="Hello, World!"

# Single quotes also work as delimiters — but note escape sequences are still
# processed inside them, the same as double quotes (see table below)
MESSAGE='Line one\nLine two'

Supported Features

Feature	Example	Notes
Basic assignment	`KEY=value`	Standard format
Comments	`# comment`	Lines starting with `#`
Blank lines		Ignored
Quoted values	`KEY="value with spaces"`	Single or double quotes
Inline comments	`KEY=value # comment`	After whitespace
Escape sequences	`KEY="line1\nline2"`	Processed inside both single- and double-quoted values
Empty values	`KEY=`	Sets empty string

Not Supported

For security reasons, variable expansion is not supported:

# These do NOT work - $VAR is literal, not expanded
BASE_URL=http://localhost
API_URL=$BASE_URL/api    # Becomes literal "$BASE_URL/api"

Accessing Variables in Agents

Environment variables are available via standard Python os.environ:

import os

def my_node(state):
    api_key = os.environ.get("OPENAI_API_KEY")
    log_level = os.environ.get("LOG_LEVEL", "info")

    # Use the variables...

With LangChain

LangChain automatically reads common environment variables:

from langchain_openai import ChatOpenAI

# Automatically uses OPENAI_API_KEY from environment
llm = ChatOpenAI(model="gpt-4")

With Ollama

Configure the Ollama base URL for local development:

# .env
OLLAMA_BASE_URL=http://host.docker.internal:11434

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="llama3.2",
    base_url=os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
)

Production: Built Images

When deploying with agentvisor build, .env files are automatically excluded from the image to prevent accidentally packaging secrets. In sandboxed modes (gVisor, Docker), agent processes do not inherit host environment variables by default — .env files are one mechanism for providing user-defined variables to the sandbox.

A second, simpler mechanism exists for forwarding specific variables that are already set in the host's own environment: guest.environment_passthrough (env: AGENTVISOR_GUEST_ENVIRONMENT_PASSTHROUGH, comma-separated names). Unlike .env files, it doesn't require mounting anything — the host runtime reads the named variables from its own environment and forwards them to the guest at startup.

You can use .env files at runtime by mounting them into the container and pointing to them with AGENTVISOR_GUEST_ENVIRONMENT_FILES:

docker run --security-opt seccomp=unconfined \
    --security-opt apparmor=unconfined \
    -p 8090:8090 \
    -v /path/to/secrets.env:/etc/agentvisor/secrets.env:ro \
    -e AGENTVISOR_GUEST_ENVIRONMENT_FILES=/etc/agentvisor/secrets.env \
    my-agent:v1

In Kubernetes, mount a Secret as a file:

containers:
  - name: my-agent
    image: my-agent:v1
    env:
      - name: AGENTVISOR_GUEST_ENVIRONMENT_FILES
        value: /etc/agentvisor/secrets.env
    volumeMounts:
      - name: agent-secrets
        mountPath: /etc/agentvisor
        readOnly: true
volumes:
  - name: agent-secrets
    secret:
      secretName: agent-env-file

For API keys, consider Credential Brokering — a more secure approach where real credentials never enter the sandbox at all.

Security Considerations

What's Secure

Variables are securely transmitted from host to guest, not passed as command-line arguments
Variables don't appear in container inspect or OCI specs
Works uniformly across all sandbox modes (none, docker, gvisor)

Best Practices

Never commit .env files - Add to .gitignore:
```
.env
.env.local
.env.*.local
```

Use .env.example for documentation:

# .env.example (committed to git)
OPENAI_API_KEY=your-key-here
DATABASE_URL=postgres://localhost/mydb

Separate environments:

agentvisor run ./my-agent --env-files=.env.development
agentvisor run ./my-agent --env-files=.env.production

Multiple files with overrides (later files override earlier):
```
agentvisor run ./my-agent --env-files=base.env,secrets.env
```

Configuration Reference

CLI Flags

Command	Flag	Description
`agentvisor run`	`--env-files`	Comma-separated paths to `.env` files (later files override)
`agentvisor serve`	`--env-files`	Comma-separated paths to `.env` files (later files override)

Environment Variable

export AGENTVISOR_GUEST_ENVIRONMENT_FILES=/path/to/.env
# Multiple files:
export AGENTVISOR_GUEST_ENVIRONMENT_FILES=base.env,secrets.env

Config File

# agentvisor.yaml
guest:
  environment_files: ./my-agent/.env
  # Or multiple files:
  environment_files: "base.env,secrets.env"

Troubleshooting

Variables Not Available

Check file path: Ensure the .env file exists and the path is correct
Check file format: Ensure valid KEY=value format
Check key names: Environment variable names must start with a letter or underscore

Auto-Discovery Not Working

Auto-discovery only checks for .env in the agent source directory. If your file has a different name or location, use --env-files explicitly.

Invalid Key Names

Environment variable names must:

Start with a letter or underscore
Contain only letters, digits, and underscores

Invalid examples:

1INVALID=value      # Can't start with number
MY-VAR=value        # Can't contain hyphen
MY.VAR=value        # Can't contain dot

Overview​

Basic Usage​

Auto-Discovery​

Explicit Path​

File Format​

Supported Features​

Not Supported​

Accessing Variables in Agents​

With LangChain​

With Ollama​

Production: Built Images​

Security Considerations​

What's Secure​

Best Practices​

Configuration Reference​

CLI Flags​

Environment Variable​

Config File​

Troubleshooting​

Variables Not Available​

Auto-Discovery Not Working​

Invalid Key Names​

See Also​