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
cd governance-layer

python3 -m venv .venv
.venv/bin/python3 -m pip install -r requirements.txt

./atested start
./atested status

First start

./atested start creates the runtime directory, Ed25519 signing key, machine identity, primary machine registry, and initial signed QA bootstrap snapshot. It then starts the supervisor, proxy, dashboard, quality service, and sync service.

The signing key is stored at gov_runtime/.atested-signing-key.pem with mode 0600. You do not need to generate or configure a signing key manually.

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 any provider-specific credentials or upstream overrides before running ./atested start.

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, set the environment variable before starting Atested:

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, set the environment variable before starting Atested:

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. Set the environment variable before starting Atested:

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.

Lifecycle commands

Use the lifecycle command instead of starting the proxy or dashboard directly:

./atested start
./atested status

The supervised proxy listens on http://127.0.0.1:8080 and the dashboard on http://localhost:9700.

Options:

./atested start --user-identity "my-dev-machine" labels the installation in the chain. You can also set ATESTED_USER_LABEL.

./atested start --upstream http://127.0.0.1:18090 selects an alternate Anthropic-compatible upstream for development or testing.

Multi-machine setup

The first machine in an installation becomes the primary. It runs the proxy, dashboard, supervisor, and sync service. Additional machines enabled by the selected product entitlement 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 their product entitlements. These machine limits are product entitlements, not restrictions in the BSL itself. Commercial or organizational production use, including entirely internal organizational use, requires a paid commercial license.

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

Confirm the supervisor and all services are running, then open the Atested Dashboard.

./atested status

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

./atested stop

Stop Atested before uninstalling. This shuts down the supervisor and all managed services cleanly. Your chain data remains on disk. It’s yours.