Vault & Secrets

The vault is an encrypted storage system for sensitive information like API keys, passwords, and tokens.

Overview

┌─────────────────────────────────────────────────────┐
│                    Secrets Vault                     │
├─────────────────────────────────────────────────────┤
│                                                      │
│  ┌──────────────────────────────────────────────┐  │
│  │              Encrypted Storage                │  │
│  │                                               │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐      │  │
│  │  │ API Key │  │ Password│  │  Token  │      │  │
│  │  │ (enc)   │  │ (enc)   │  │ (enc)   │      │  │
│  │  └─────────┘  └─────────┘  └─────────┘      │  │
│  │                                               │  │
│  └──────────────────────────────────────────────┘  │
│                                                      │
│  Location: ~/.moxxy/agents/<name>/vault/            │
│                                                      │
└─────────────────────────────────────────────────────┘

What Goes in the Vault

Secret Type	Examples
API Keys	OpenAI, Google, service keys
Tokens	Telegram bot token, OAuth tokens
Passwords	Database passwords, service credentials
Certificates	SSH keys, TLS certificates
Custom	Any sensitive configuration

Managing Secrets

Via Web Dashboard

1. Open web dashboard
2. Go to Config → Vault
3. Click Add Secret
4. Enter key name and value
5. Click Save

Via CLI

# Store a secret
moxxy run --agent default --prompt "Store 'my-api-key-123' in vault as MY_API_KEY"

# Retrieve a secret
moxxy run --agent default --prompt "What is the value of MY_API_KEY?"

# Update a secret
moxxy run --agent default --prompt "Update MY_API_KEY to 'new-key-456'"

# Delete a secret
moxxy run --agent default --prompt "Remove MY_API_KEY from vault"

Via API

Store:

curl -X POST http://localhost:17890/api/agents/default/vault \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_PASSWORD", "value": "supersecret123"}'

Retrieve:

curl http://localhost:17890/api/agents/default/vault/DATABASE_PASSWORD

List:

curl http://localhost:17890/api/agents/default/vault

Delete:

curl -X DELETE http://localhost:17890/api/agents/default/vault/DATABASE_PASSWORD

Using Secrets in Skills

Skills can access vault secrets:

Shell Skills

#!/bin/bash
# Access secret via environment
API_KEY=$(cat ~/.moxxy/agents/default/vault/api_key.enc | moxxy-vault decrypt)

curl -H "Authorization: Bearer $API_KEY" https://api.example.com

Python Skills

import os
import subprocess

def get_secret(key):
    # Use moxxy vault CLI or API
    result = subprocess.run(
        ['moxxy', 'run', '--agent', 'default', '--prompt', f'Get vault value for {key}'],
        capture_output=True, text=True
    )
    return result.stdout.strip()

api_key = get_secret('MY_API_KEY')

Via Agent Invocation

Agents can access vault in their reasoning:

User: "Call the API with my stored key"

Agent: I'll use your stored API key to make the request.
<invoke name="host_shell">["curl -H 'Authorization: Bearer $VAULT_API_KEY' https://api.example.com"]</invoke>

Predefined Secrets

Moxxy uses certain secrets automatically:

LLM Configuration

Key	Purpose
openai_api_key	OpenAI API key
google_api_key	Google API key
xai_api_key	Z.Ai (Grok) API key
llm_model	Default model name
llm_provider	Active provider

Gateway Configuration

Key	Purpose
gateway_host	API bind address
gateway_port	API port
web_ui_port	Web dashboard port

Channel Configuration

Key	Purpose
telegram_token	Telegram bot token
discord_token	Discord bot token
slack_bot_token	Slack bot token
slack_app_token	Slack app-level token

Embedding Configuration

Key	Purpose
embedding_model	Model for vector embeddings

Security Model

Encryption

Secrets are encrypted at rest using:

• AES-256-GCM for symmetric encryption
• Per-agent encryption keys
• Keys derived from agent identity

Access Control

• Each agent has its own vault
• Vaults are isolated between agents
• No cross-agent secret access

Memory Safety

• Secrets are decrypted only when needed
• Cleared from memory after use
• Never logged or persisted in plaintext

Best Practices

Naming Conventions

Use clear, consistent names:

✅ OPENAI_API_KEY
✅ DATABASE_PASSWORD_PROD
✅ TELEGRAM_BOT_TOKEN

❌ key1
❌ secret
❌ password

Secret Rotation

Regularly rotate sensitive secrets:

1. Generate new secret
2. Update in vault
3. Restart affected services
4. Revoke old secret

Minimal Access

Only store what's needed:

• Don't store long-lived tokens if short-lived work
• Don't store admin keys if read-only works
• Remove unused secrets

Backup Considerations

The vault is stored in:

~/.moxxy/agents/<name>/vault/

When backing up:

• Backup the entire vault directory
• Ensure backups are encrypted
• Test restoration periodically

API Reference

List Secrets

GET /api/agents/:name/vault

Response:

{
  "secrets": [
    {"key": "OPENAI_API_KEY", "created_at": "2024-01-15T10:00:00Z"},
    {"key": "DATABASE_PASSWORD", "created_at": "2024-01-15T10:00:00Z"}
  ]
}

Get Secret

GET /api/agents/:name/vault/:key

Response:

{
  "key": "OPENAI_API_KEY",
  "value": "sk-xxx...",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Store Secret

POST /api/agents/:name/vault
Content-Type: application/json

{
  "key": "NEW_SECRET",
  "value": "secret_value"
}

Update Secret

PUT /api/agents/:name/vault/:key
Content-Type: application/json

{
  "value": "new_secret_value"
}

Delete Secret

DELETE /api/agents/:name/vault/:key

Troubleshooting

Secret Not Found

Error: Secret 'MY_KEY' not found

Solution:

1. Check spelling and case
2. Verify secret exists: GET /api/agents/:name/vault
3. Check correct agent

Decryption Failed

Error: Failed to decrypt secret

Solution:

1. Vault may be corrupted
2. Check agent directory permissions
3. Recreate the secret

Access Denied

Error: Access denied to vault

Solution:

1. Check agent is running
2. Verify file permissions
3. Check gateway status

Secret Exposed in Logs

DANGER

If a secret appears in logs:

1. Rotate the secret immediately
2. Check how it was exposed
3. Review agent persona for accidental logging

Migration

Export Secrets

# List all secrets
curl http://localhost:17890/api/agents/default/vault > secrets.json

Import Secrets

# Restore from backup
for key in $(cat secrets.json | jq -r '.secrets[].key'); do
  # Re-add each secret
done

Transfer Between Agents

# Get from source
VALUE=$(curl http://localhost:17890/api/agents/source/vault/MY_KEY | jq -r '.value')

# Store in target
curl -X POST http://localhost:17890/api/agents/target/vault \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"MY_KEY\", \"value\": \"$VALUE\"}"