← Back to Docs

Migration Guide

Upgrade your security posture from file to keychain to hardware step-by-step

Security Progression Path

File Backend

AES-256 encrypted file

→

Keychain Backend

OS-native protection

→

Hardware Backend

FIPS 140-3 HSM

Migrating from .env Files

Many projects store credentials in .env files. Here's how to migrate to AVP:

1 Install AVP CLI

pip install avp-cli

2 Create a new vault

# Create an encrypted vault file
avp init --backend file --path ~/.avp/vault.enc

# You'll be prompted to create a password
Enter vault password: ********
Confirm password: ********
Vault created successfully!

3 Import from .env

# Import all variables from .env file
avp import .env --format dotenv --workspace my-agent

Imported 5 secrets:
  - OPENAI_API_KEY
  - DATABASE_URL
  - REDIS_URL
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY

4 Update your code

Replace environment variable access with AVP:

# Before: Using .env
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

# After: Using AVP
from avp import AVPClient, FileBackend

client = AVPClient(FileBackend("~/.avp/vault.enc", password))
session = client.authenticate("my-agent")
api_key = client.retrieve(session.session_id, "OPENAI_API_KEY").value.decode()

5 Remove .env from version control

# Add to .gitignore
echo ".env" >> .gitignore

# Remove from git history (if previously committed)
git rm --cached .env
git commit -m "Remove .env from version control"
Security Note: After migration, securely delete your .env file. Simply deleting it may leave traces on disk. Use secure deletion tools or overwrite the file before deleting.

File to Keychain Migration

Upgrade from file backend to OS-native keychain for better security:

1 Export from file backend

avp export --backend file --path ~/.avp/vault.enc \
    --workspace my-agent --output /tmp/secrets.json

# Secrets are temporarily in plaintext - handle carefully!

2 Import to keychain backend

avp import /tmp/secrets.json --backend keychain \
    --service-name my-app-avp --workspace my-agent

Imported 5 secrets to keychain

3 Securely delete temporary file

# macOS
rm -P /tmp/secrets.json

# Linux
shred -u /tmp/secrets.json

# Windows
cipher /w:C:\temp

4 Update your code

# Before: File backend
from avp import AVPClient, FileBackend

client = AVPClient(FileBackend("~/.avp/vault.enc", password))

# After: Keychain backend
from avp import AVPClient, KeychainBackend

client = AVPClient(KeychainBackend(service_name="my-app-avp"))
Benefit: With keychain backend, you no longer need to manage a password. The OS protects your credentials using the system keychain, which may be backed by the Secure Enclave or TPM.

Keychain to Hardware Migration

For maximum security, migrate to hardware-backed storage with NexusClaw:

1 Connect NexusClaw device

# Verify device is connected
avp discover --backend hardware

Device: NexusClaw v1.0
Serial: NC-2024-001234
Firmware: 0.1.0
Secure Element: TROPIC01
Status: Ready

2 Initialize device (first time only)

# Set up device PIN
avp hardware init

Enter new PIN (6-8 digits): ******
Confirm PIN: ******
Device initialized successfully!

# Important: Save your recovery seed phrase
Recovery phrase:
  1. abandon  2. ability  3. able  ...

Store this phrase securely - it cannot be recovered!

3 Export from keychain

avp export --backend keychain --service-name my-app-avp \
    --workspace my-agent --output /tmp/secrets.json

4 Import to hardware

avp import /tmp/secrets.json --backend hardware \
    --workspace my-agent

Enter device PIN: ******
Importing secrets to hardware...
  - OPENAI_API_KEY [slot 1]
  - DATABASE_URL [slot 2]
  - AWS_ACCESS_KEY_ID [slot 3]
  ...
Imported 5 secrets to hardware

5 Update your code

# Before: Keychain backend
from avp import AVPClient, KeychainBackend

client = AVPClient(KeychainBackend(service_name="my-app-avp"))

# After: Hardware backend
from avp import AVPClient, HardwareBackend

client = AVPClient(HardwareBackend())  # Auto-detects NexusClaw
Hardware Limits: NexusClaw has a limited number of storage slots (typically 32-64). For large numbers of secrets, consider keeping less sensitive ones in keychain and only critical secrets in hardware.

Multi-Backend Strategy

For production systems, consider using multiple backends based on sensitivity:

from avp import AVPClient, FileBackend, KeychainBackend, HardwareBackend

# Tiered security approach
class TieredVault:
    def __init__(self):
        # Critical secrets (API keys, private keys) -> Hardware
        self.hardware = AVPClient(HardwareBackend())

        # Sensitive secrets (database URLs) -> Keychain
        self.keychain = AVPClient(KeychainBackend("my-app"))

        # Development/test secrets -> File
        self.file = AVPClient(FileBackend("./dev-vault.enc", "dev-pass"))

    def get_secret(self, name: str, tier: str = "keychain"):
        if tier == "hardware":
            client = self.hardware
        elif tier == "keychain":
            client = self.keychain
        else:
            client = self.file

        session = client.authenticate("default")
        return client.retrieve(session.session_id, name)

# Usage
vault = TieredVault()
api_key = vault.get_secret("OPENAI_API_KEY", tier="hardware")
db_url = vault.get_secret("DATABASE_URL", tier="keychain")

Migration Checklist