Skip to main content

Configuring AgentVisor™

In the previous chapter, you learned how to configure logging with AGENTVISOR_LOG_LEVEL and its component overrides (e.g., info,agent=debug). That is one of many runtime settings. Before we dive into policies and authentication, let's understand AgentVisor's configuration system.

What You'll Learn​

  • The difference between agent config and runtime config
  • Using environment variables to configure the host runtime
  • Creating and using an agentvisor.yaml config file
  • Config file search locations and the AGENTVISOR_CONFIG override
  • Configuration precedence: env vars > config file > defaults

Two Layers of Configuration​

AgentVisor has two separate configuration layers:

LayerWhat It ConfiguresHow to Set ItCovered In
Agent configYour agent's environment (API keys, model names).env filesConfiguring Your Agent
Runtime configThe AgentVisor host runtime (logging, API port, policies, Temporal)AGENTVISOR_* env vars or agentvisor.yamlThis chapter

Agent config flows into the sandbox where your Python code runs. Runtime config controls the host runtime that manages sandboxes, proxies HTTP requests, and enforces policies.

Environment Variables​

All runtime settings can be set via environment variables with the AGENTVISOR_ prefix. You've already used two of them:

# Global log level (controls proxy, policy, lifecycle, and agent logs)
AGENTVISOR_LOG_LEVEL=warn,agent=debug

The grammar is <global>[,<component>=<level>]*, so you can set a quiet global level while turning up verbosity for a specific component like agent.

The naming convention maps YAML config paths to environment variable names by uppercasing and replacing dots with underscores:

YAML PathEnvironment Variable
api.listen_addrAGENTVISOR_API_LISTEN_ADDR
temporal.targetAGENTVISOR_TEMPORAL_TARGET
authz.typeAGENTVISOR_AUTHZ_TYPE
authz.embedded.policy_domain_filesAGENTVISOR_AUTHZ_EMBEDDED_POLICY_DOMAIN_FILES

logging.level, logging.format, and logging.output are exceptions to this rule, kept as AGENTVISOR_LOG_LEVEL / AGENTVISOR_LOG_FORMAT / AGENTVISOR_LOG_OUTPUT (no LOGGING_ prefix) for backward compatibility with the CLI's original flat log flags.

The Config File​

For settings you want to persist across sessions, create an agentvisor.yaml file. Here's a focused example:

# agentvisor.yaml
logging:
  level: info
  format: plain

api:
  listen_addr: ":8090"

temporal:
  target: "localhost:7233"

When agentvisor serve or agentvisor run starts, it automatically searches for this file.

Config File Search Locations​

AgentVisor checks these locations in order, using the first file found:

  1. ./agentvisor.yaml — current working directory
  2. $HOME/.config/agentvisor/agentvisor.yaml — user config directory
  3. /etc/agentvisor/agentvisor.yaml — system config directory

Overriding the Config File Location​

Use the AGENTVISOR_CONFIG environment variable to specify an explicit path:

AGENTVISOR_CONFIG=/path/to/my-config.yaml agentvisor serve .

This overrides the default search paths entirely.

Configuration Precedence​

When the same setting is specified in multiple places, this precedence applies (later wins):

  1. Default values (lowest priority)
  2. Base config file (agentvisor.yaml)
  3. conf.d/ drop-in fragments (alphabetically sorted, adjacent to base config)
  4. Overlay files (AGENTVISOR_CONFIG_FILES env var, then --config flags)
  5. Environment variables (highest priority)

For example, if your agentvisor.yaml sets logging.level: info but you run with AGENTVISOR_LOG_LEVEL=debug, the log level will be debug — the environment variable wins.

tip

For multi-environment setups, overlays and conf.d/ fragments let you share a base config and override only what differs per environment. See the Multi-Config Files reference for patterns and examples.

Development vs Production​

During development with agentvisor serve or agentvisor run, the host runtime runs natively on your machine. It automatically discovers agentvisor.yaml and policy files from your local filesystem.

In production (images built with agentvisor build), these files must be explicitly provided — typically via volume mounts or environment variables. You'll see how in the Deploying Your Agent chapter.

Try It​

Let's see configuration in action, using the chatbot from Your First Agent. That project already ships its own agentvisor.yaml (it holds the SSRF allowlist the chatbot's Ollama call depends on), so rather than overwrite it, layer an overlay file on top using the AGENTVISOR_CONFIG_FILES mechanism from the precedence table above:

# try-it.yaml
logging:
  level: debug

api:
  listen_addr: ":9090"

Run the agent with the overlay applied:

AGENTVISOR_CONFIG_FILES=try-it.yaml agentvisor serve .

You should see:

  • Debug-level logs in the output (more verbose than the default info)
  • The API listening on port 9090 instead of the default 8090

The base agentvisor.yaml is still in effect underneath — maps deep-merge, so only the logging and api keys from the overlay are applied; the SSRF allowlist is untouched.

Now override the log level with an environment variable:

AGENTVISOR_CONFIG_FILES=try-it.yaml AGENTVISOR_LOG_LEVEL=warn agentvisor serve .

The log output becomes much quieter — only warnings and errors — demonstrating that the environment variable takes precedence over both the overlay and the base config file.

Clean up by removing the overlay file when you're done:

rm try-it.yaml

Next Steps​