agentmetrics-server

Self-hosted AgentMetrics API server. Install it once and every agent instrumented with the AgentMetrics SDK reports to your own dashboard showing cost, latency, token usage, tool calls, and failures, with no cloud account and no data leaving your infrastructure.

Install

pip install agentmetrics-server

Requires Python 3.11 or later.

Quickstart

Start the server in the foreground:

agentmetrics-server

Dashboard → http://localhost:3099
API → http://localhost:8099

Data is stored in agentmetrics.db in the current directory by default.

Always running

For continuous 24/7 observation across reboots and crashes, install as a system service instead of running in the foreground:

agentmetrics install

This registers the server with systemd on Linux, launchd on macOS, or Task Scheduler on Windows, starts it immediately, and configures it to come back automatically after any restart or crash. The database is stored in a persistent OS data directory so it is never lost across reinstalls.

agentmetrics install              # install and start with defaults
agentmetrics install --port 9000  # custom port
agentmetrics install --db postgresql://user:pass@localhost/mydb

agentmetrics start                # start a stopped service
agentmetrics stop                 # stop without uninstalling
agentmetrics restart              # restart
agentmetrics status               # show service state and HTTP health check
agentmetrics uninstall            # remove the service

Platform behaviour

On Linux, the service unit is written to ~/.config/systemd/user/agentmetrics.service when run as a normal user, or /etc/systemd/system/agentmetrics.service when run as root. Logs are available via journalctl --user -u agentmetrics -f.

On macOS, the plist is written to ~/Library/LaunchAgents/com.agentmetrics.server.plist and logs go to ~/Library/Logs/AgentMetrics/.

Configuration

All options can be passed as flags or set via environment variables.

SQLite (default)

No setup needed. The database is created automatically in the current directory, or in the OS data directory when running as a service.

PostgreSQL

pip install "agentmetrics-server[postgres]"
agentmetrics-server --db postgresql://user:pass@localhost/agentmetrics

Or as a persistent service:

agentmetrics install --db postgresql://user:pass@localhost/agentmetrics

Foreground options

agentmetrics-server --port 9000
agentmetrics-server --host 127.0.0.1     # localhost only
agentmetrics-server --db postgresql://user:pass@localhost/mydb
agentmetrics-server --open               # open dashboard in browser on start

Health check

GET /health  →  {"status": "ok"}

License

MIT