Configuration

Attestix is configured via environment variables. No config file is needed for basic usage.

Environment Variables

Setting Environment Variables

Linux/macOS

export ATTESTIX_DATA_DIR=/var/lib/attestix
export ATTESTIX_LOG_LEVEL=DEBUG
python -m attestix.main

Windows

$env:ATTESTIX_DATA_DIR = "C:\attestix-data"
$env:ATTESTIX_LOG_LEVEL = "DEBUG"
python -m attestix.main

.env file

Create a .env file in the Attestix directory:

ATTESTIX_DATA_DIR=/var/lib/attestix
ATTESTIX_LOG_LEVEL=DEBUG

Attestix uses python-dotenv and loads .env automatically.

Storage Configuration

By default, Attestix stores all data in JSON files under ATTESTIX_DATA_DIR (default ~/.attestix):

attestix/
  main.py
  identities.json        # Created on first identity creation
  credentials.json       # Created on first credential issuance
  compliance.json        # Created on first compliance profile
  provenance.json        # Created on first provenance record
  reputation.json        # Created on first interaction recording
  delegations.json       # Created on first delegation
  .signing_key.json      # Created on first run (DO NOT SHARE)
  .keypairs.json         # Created on first DID key generation (DO NOT SHARE)

To use a custom directory:

export ATTESTIX_DATA_DIR=/var/lib/attestix

All JSON files will be created in that directory instead.

Signing Key Management

On first run, Attestix generates an Ed25519 keypair and stores it in .signing_key.json. The default signer uses this key for supported signed artifacts. Audit-chain hashes and stored metadata are not proof that every record has an independent signature.

Important: Back up .signing_key.json securely. If you lose it, you cannot create new artifacts that chain to the same DID.

The default key lives under ATTESTIX_DATA_DIR. ATTESTIX_KEY_FILE is not a supported configuration variable. Review the public signer interface for explicit signer/key selection, and validate custody and restoration before deployment.

Blockchain Configuration

Blockchain anchoring is optional. To enable it, you need a funded wallet on Base L2.

Base Sepolia (Testnet)

export BASE_RPC_URL=https://sepolia.base.org
export BASE_WALLET_KEY=your_private_key_hex_no_0x_prefix

Base Mainnet

export BASE_RPC_URL=https://mainnet.base.org
export BASE_WALLET_KEY=your_private_key_hex_no_0x_prefix

Warning: The BASE_WALLET_KEY is a private key that controls funds. Never commit it to version control. Use environment variables or a secrets manager.

Gas Estimation

Use estimate_anchor_cost to check costs before anchoring:

estimate_anchor_cost(artifact_type="identity")

Returns estimated gas in ETH at current gas prices.

MCP Client Configuration

Claude Code

Add to ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows):

{
  "mcpServers": {
    "attestix": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "attestix.main"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "attestix": {
      "command": "python",
      "args": ["-m", "attestix.main"]
    }
  }
}

Any MCP Client

Attestix communicates over stdio using the MCP protocol. Start the server with:

python -m attestix.main

Connect your MCP client to the process's stdin/stdout.

Multi-Instance Setup

Supported JSON operations use a shared storage lock across threads and processes. The lock provides isolation, not rollback of multi-collection writes or distributed deployment acceptance. Validate filesystem locking, storage durability, key custody, recovery and instance lifecycle before sharing a data directory. Keep development and production data/keys separate.

The default REST surface is single-tenant. Non-default X-Attestix-Tenant headers are rejected; do not present that header as a multi-tenant authorization boundary. Configure ATTESTIX_API_KEY through an approved runtime secret channel; no-auth mode is for isolated development/tests only.

Docker

Running Attestix

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
ENV ATTESTIX_DATA_DIR=/data
VOLUME /data
CMD ["python", "main.py"]

docker build -t attestix .
docker run -v attestix-data:/data attestix

Running the Test Suite

The project includes Dockerfile.test which runs all 358 tests (unit, e2e, and conformance benchmarks; 1 skipped on Windows) in a clean container:

docker build -f Dockerfile.test -t attestix-bench . && docker run --rm attestix-bench

This validates:

• 193 unit and end-to-end tests
• 91 conformance benchmarks (RFC 8032, W3C VC, W3C DID, UCAN, MCP, performance)
• Performance thresholds for all cryptographic and service operations

Signing keys are stored locally by the default signer. Protect permissions, versioned backups and recovery access; a key replacement changes issuer identity. Source configuration and a green health response do not demonstrate production custody.