Installation

Install the opena2a CLI for local identity and auditing, or self-host the AIM server for centralized agent identity management across a fleet.

opena2a CLI

Local identity, capability policy, trust scoring, and a cross-tool audit log. No server required. No configuration to start.

Run without installing
npx opena2a-cli identity create --name my-agent
Install globally (npm)
npm install -g opena2a-cli
Homebrew (macOS/Linux)
brew install opena2a-org/tap/opena2a
View on GitHub →

Python SDK (cloud)

To use AIM Cloud, install the Python SDK and authenticate. This is the fastest path and needs no infrastructure.

pip install aim-sdk
aim-sdk login                    # OAuth to aim.opena2a.org, or --url for self-hosted

npm package (no server required)

For lightweight cases that do not need a centralized server, use @opena2a/aim-core directly. Ed25519 identity, capability policy, trust scoring, and a local audit log, all in-process.

npm install @opena2a/aim-core
aim-core guide →

Self-host the AIM server

The server adds a REST API, dashboard, PostgreSQL audit storage, OAuth, 5-step Fine-Grained Authorization, the 9 factor behavioral trust score, MCP attestation, and SIEM adapters. Pick the quickstart script for a one-command stack, or build from source.

Quickstart script

Brings up the AIM server, dashboard, PostgreSQL, and Redis. Verify the script against the SHA in the latest release notes before running it.

curl -sSLO https://raw.githubusercontent.com/opena2a-org/agent-identity-management/main/scripts/quickstart.sh
shasum -a 256 quickstart.sh      # verify against the SHA in the latest release notes
bash quickstart.sh

The dashboard is served at http://localhost:3000 and the API at http://localhost:8080. Login credentials are generated and printed at the end of the run.

From source

For development or a custom stack, clone the repository and generate local-dev secrets.

git clone https://github.com/opena2a-org/agent-identity-management.git
cd agent-identity-management

# Generate local-dev secrets (one-time setup)
./scripts/gen-dev-secrets.sh > .env

# Minimal dev stack
docker compose up -d aim-postgres aim-redis aim-backend aim-frontend

# Health check
curl -fsS localhost:8080/healthz

The full docker-compose.yml also brings up Elasticsearch, MinIO, NATS, Prometheus, Grafana, and Loki. The minimal command above skips those services. Prerequisites: Docker, Go 1.23+, Node 20+, Python 3.11+.

Production deployment

Deployment references for Azure, GCP, and AWS live in infrastructure/DEPLOYMENT.md. The reference deployment runs on a managed container environment with at least 8 GB RAM and 4 vCPUs.

System requirements

  • • CPU: 2 vCPUs (x86_64 or ARM64), 4 for production
  • • Memory: 4 GB RAM, 8 GB for production
  • • Storage: 20 GB SSD
  • • Database: PostgreSQL 14+
  • • Cache: Redis 6+ (optional)

Environment variables

Required when building from source. The quickstart script generates these for you.

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=aim_user
POSTGRES_PASSWORD=<generated>
POSTGRES_DB=aim

# Redis (optional but recommended)
REDIS_HOST=localhost
REDIS_PORT=6379

# Security
JWT_SECRET=<min-32-chars>
ENCRYPTION_KEY=<generated>

# API
API_PORT=8080
API_HOST=0.0.0.0

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8080

Verify the installation

Confirm the server is healthy:

curl http://localhost:8080/healthz

# Expected response:
{ "status": "healthy" }

With a healthy status, AIM is running. Continue to the quick start to register your first agent.

Troubleshooting

Database connection failed

Ensure PostgreSQL is running and the connection details are correct.

psql -h localhost -U aim_user -d aim

Port already in use

Check whether another service holds the port:

lsof -i :8080  # API lsof -i :3000  # dashboard

Docker Compose issues

View logs to diagnose:

docker compose logs -f