Installation guide

Installation guide

Atested is an HTTP proxy that sits between your AI agent and the model provider. Setup takes about five minutes.

Requirements

Install

Clone the repository and install the Python dependencies.

git clone https://github.com/atested/governance-layer.git atested
cd atested
python3 -m venv mcp/.venv
mcp/.venv/bin/python3 -m pip install -r mcp/requirements.txt

Generate a signing key

Atested signs chain records with an Ed25519 key. This makes the chain cryptographically verifiable by anyone who has the public key.

openssl genpkey -algorithm Ed25519 -out signing.key
chmod 600 signing.key

Set the environment variable so the proxy finds the key on startup:

export GOV_SIGNING_KEY_PATH=./signing.key

The proxy logs the key fingerprint when it starts. Every chain record from this point forward is signed. If you skip this step, records are written unsigned and cannot be independently verified.

Provider setup

Atested governs operations at the API transport layer. Each provider has its own API structure, authentication, and response format. The proxy handles these differences internally. Configure the provider you use before starting the proxy.

Anthropic

Set your API key. Anthropic is the default upstream, so no additional flags are needed.

export ANTHROPIC_API_KEY=sk-ant-...

The proxy route is /anthropic. You will point your agent's base URL to http://localhost:8080/anthropic.

OpenAI

Set your API key. The default upstream for OpenAI is https://api.openai.com.

export OPENAI_API_KEY=sk-...

To override the default upstream:

python3 -m proxy.server --openai-upstream https://api.openai.com

Or set the environment variable:

export OPENAI_UPSTREAM=https://api.openai.com

The proxy route is /openai. Point your agent's base URL to http://localhost:8080/openai.

OpenAI's action format differs from Anthropic's. The classifier handles the structural differences, but classification confidence may vary between providers because the evidence available in action parameters is provider-dependent.

Gemini

Set your API key. The default upstream for Gemini is https://generativelanguage.googleapis.com.

export GEMINI_API_KEY=...

To override the default upstream:

python3 -m proxy.server --gemini-upstream https://generativelanguage.googleapis.com

Or set the environment variable:

export GEMINI_UPSTREAM=https://generativelanguage.googleapis.com

The proxy route is /gemini. Point your agent's base URL to http://localhost:8080/gemini.

Gemini uses a different response structure (functionCall parts instead of Anthropic's tool_use blocks). The proxy handles this automatically. Streaming responses via streamGenerateContent are also supported.

LiteLLM

LiteLLM is a proxy that provides a unified OpenAI-compatible interface to multiple providers. Atested can sit in front of LiteLLM, governing operations before they reach any downstream model.

LiteLLM has no default upstream — you must configure it explicitly:

python3 -m proxy.server --litellm-upstream http://localhost:4000

Or set the environment variable:

export LITELLM_UPSTREAM=http://localhost:4000

The proxy route is /litellm. Point your agent's base URL to http://localhost:8080/litellm.

LiteLLM uses the same action format as OpenAI. The classifier handles it the same way.

Other providers

Any provider whose API follows the standard chat completions format can work through the OpenAI or LiteLLM routes. Classification accuracy depends on how much structural evidence the provider includes in its action payloads.

Start the proxy

Run the proxy using the environment variables you configured in Provider setup. For Anthropic (the default):

python3 -m proxy.server

For other providers, include the provider-specific upstream flag as shown in your provider's section above (e.g. --openai-upstream, --gemini-upstream, --litellm-upstream).

The proxy starts on http://127.0.0.1:8080 by default. You'll see a startup line confirming the port and the upstream provider URL.

Options:

--port 9090 to use a different port

--host 0.0.0.0 to bind to all interfaces

--user-identity "my-dev-machine" to label this install in the chain (or set ATESTED_USER_LABEL in your environment)

Multi-machine setup

The first machine in an installation becomes the primary. It runs the proxy, dashboard, supervisor, and sync service. Additional licensed machines join as remotes. Remotes govern locally and sync verified records back to the primary.

Primary

./atested start --role primary

First start creates gov_runtime, assigns a machine ID, generates the machine signing key, and bootstraps the primary machine registry.

Remote

./atested start --role remote --primary http://PRIMARY_HOST:PORT

The remote creates its own machine identity, sends a signed join request to the primary, and waits for local operator confirmation on the primary before it is added to the registry. After confirmation, the remote receives the current approval store, policy hash, Communications messages, and version information during sync.

Personal tier is single-machine. Personal Plus supports up to three machines. Crew, Team, and Institution tiers support multi-machine deployments according to license terms.

Point your agent at the proxy

This is the one configuration change. Tell your agent to send API traffic through Atested instead of directly to the model provider.

For Anthropic (Claude Code, agents using the Anthropic SDK):

export ANTHROPIC_BASE_URL=http://localhost:8080/anthropic

For OpenAI:

export OPENAI_BASE_URL=http://localhost:8080/openai

For Gemini or LiteLLM, point your agent at the corresponding route:

# Gemini
http://localhost:8080/gemini

# LiteLLM
http://localhost:8080/litellm

Add the export to your shell profile (.bashrc, .zshrc, or .bash_profile) so it persists across sessions.

For other agents, find the setting that controls the API endpoint and set it to the matching Atested route for your provider.

Verify Atested is running

Run your agent normally. Open the Atested Dashboard to confirm governance is active.

python3 dashboard/server.py

Open http://localhost:9700 in a browser. On the Overview page, look for:

If the dashboard shows activity, governance is working. Every operation your agent's model proposes is being classified, evaluated against policy, and recorded in the chain before the agent can act on it.

What “done” looks like

When Atested is running correctly:

Uninstall

Stop the proxy process and remove the ANTHROPIC_BASE_URL environment variable. Your agent returns to calling the provider directly. Your chain data remains on disk. It’s yours.