# Configuration

> Attestix configuration via environment variables, storage setup, signing key management, and MCP client configuration.

# Configuration

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

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ATTESTIX_DATA_DIR` | No | `~/.attestix` | Directory for JSON storage files |
| `BASE_RPC_URL` | For blockchain | - | Base L2 RPC endpoint (e.g., `https://sepolia.base.org`) |
| `BASE_WALLET_KEY` | For blockchain | - | Private key for blockchain transactions (hex string, no `0x` prefix) |
| `EAS_CONTRACT` | For blockchain | Sepolia default | Ethereum Attestation Service contract address |
| `ATTESTIX_LOG_LEVEL` | No | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

## Setting Environment Variables

### Linux/macOS

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

### Windows

```powershell
$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:

```bash
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)

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

### Base Mainnet

```bash
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):

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

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### Any MCP Client

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

```bash
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

```dockerfile
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"]
```

```bash
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:

```bash
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.