Environment Variables

AgenTopology supports environment variable references anywhere a string value is expected. This keeps secrets out of your .at files and makes topologies portable across environments.

Syntax

Reference environment variables with ${VAR_NAME}:

mcp-servers {
  postgres {
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env: {
      DATABASE_URL: "${DATABASE_URL}"
    }
  }
}

Where Variables Can Be Used

Environment variables work in any string context:

mcp-servers {
  github {
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env: {
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    }
  }

  custom-api {
    type: http
    url: "${API_BASE_URL}/mcp"
  }
}

Common Use Cases

API Keys and Tokens

env: {
  OPENAI_API_KEY: "${OPENAI_API_KEY}"
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
}

Database Connections

env: {
  DATABASE_URL: "${DATABASE_URL}"
  REDIS_URL: "${REDIS_URL}"
}

Service URLs

mcp-servers {
  backend {
    type: http
    url: "${BACKEND_MCP_URL}"
  }
}

Setting Variables

Environment variables are read from the shell environment at runtime. Set them however you normally would:

# Shell export
export DATABASE_URL="postgres://localhost:5432/mydb"

# .env file (if your platform supports it)
DATABASE_URL=postgres://localhost:5432/mydb

# Inline
DATABASE_URL="postgres://localhost:5432/mydb" agentopology run topology.at

Validation

AgenTopology validates that all referenced environment variables are set before running a topology. If a variable is missing, you get a clear error:

Error: Environment variable DATABASE_URL is not set
  → mcp-servers.postgres.env.DATABASE_URL at line 7

Tips

Never hardcode secrets in .at files. Always use ${VAR_NAME}.
Variable names follow shell conventions: uppercase with underscores.
The ${} syntax is only expanded at runtime, not at parse time. This means .at files can be safely committed to version control.
Use platform-specific secret managers (e.g. GitHub Secrets, Vercel Environment Variables) for production deployments.

Environment Variables

On this page