Configuration

API key

Your API key is available in the Maev dashboard under Settings. Keys always start with vl_.

Store your key in an environment variable, never in source code:

export MAEV_API_KEY=vl_your_key_here

import os
import maev
 
maev.init(api_key=os.environ["MAEV_API_KEY"])

Agent naming

Use the agent_name parameter to give your agent a human-readable name:

maev.init(api_key=os.environ["MAEV_API_KEY"], agent_name="Research Agent")

Naming conventions that work well:

• Use the function or role of the agent: "Email Drafter", "Lead Scorer", "Code Reviewer"
• Include the environment if you use the same key across staging and production: "Support Agent (staging)"
• Keep names consistent across deployments so history accumulates on one agent in the dashboard

Self-hosting

If you are running your own instance of Maev, pass your deployment URL as the endpoint:

maev.init(
    api_key=os.environ["MAEV_API_KEY"],
    endpoint="https://maev.your-company.internal",
)

Using a .env file

# .env
MAEV_API_KEY=vl_your_key_here
MAEV_AGENT_NAME=My Agent

from dotenv import load_dotenv
import os
import maev
 
load_dotenv()
 
maev.init(
    api_key=os.environ["MAEV_API_KEY"],
    agent_name=os.environ.get("MAEV_AGENT_NAME", "default"),
)

Docker and containers

Pass the API key as an environment variable in your container config:

# docker-compose.yml
services:
  agent:
    environment:
      - MAEV_API_KEY=vl_your_key_here

# Dockerfile
ENV MAEV_API_KEY=""

Serverless functions

In serverless environments the process is frozen immediately after your handler returns. Call maev.flush() before returning to guarantee all telemetry is delivered:

import maev
 
maev.init(api_key=os.environ["MAEV_API_KEY"], agent_name="My Lambda")
 
def handler(event, context):
    result = run_agent(event)
    maev.flush()  # flush before the process freezes
    return result

maev.flush() accepts an optional timeout (default 5 seconds):

maev.flush(timeout=10.0)

It is a no-op if called more than once, and warns (but never raises) if called before maev.init().

CI/CD

In GitHub Actions:

- name: Run agent
  env:
    MAEV_API_KEY: ${{ secrets.MAEV_API_KEY }}
  run: python agent.py