Key Agent

🔑 Key Agent

A lightweight, secure local key-value and secrets management daemon For developers, DevOps, and AI agents

Features • Quick Start • Installation • Usage • SDK • 中文文档

---

✨ Features

• 🔐 Encrypted Storage - AES-256-GCM encryption with master key stored in OS keyring, TPM, or file
• 🤖 MCP Support - Native integration with AI agents via Model Context Protocol
• 🖥️ CLI Tool - Simple and intuitive command-line interface (keyctl)
• 🔌 Go SDK - Programmatic access from Go applications
• 📝 Structured Logging - JSON logging with rotation and size limits
• 🚀 Single Binary - Zero external dependencies, easy deployment
• 🔄 Token Management - Create and manage access tokens with expiration

📦 Installation

Docker (Recommended for Quick Start)

# Using Docker Compose
git clone https://github.com/skys-mission/key-agent.git
cd key-agent

# Generate a master key (recommended)
export KEY_AGENT_MASTER_KEY=$(openssl rand -base64 32)

# Start the service
docker compose up -d

# View logs to get root token
docker logs key-agent

Docker Configuration:

| Variable | Description | |----------|-------------| | KEY_AGENT_MASTER_KEY | Base64-encoded 32-byte master key (recommended for Docker) | | KEY_AGENT_PASSPHRASE | Passphrase for encrypted master key file |

Data is stored in ~/.skys-mission/key-agent/data/ on the host via volume mount.

From Release

# macOS / Linux
curl -sL https://github.com/skys-mission/key-agent/releases/latest/download/key-agent-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o key-agent
chmod +x key-agent
sudo mv key-agent /usr/local/bin/

# CLI tool
curl -sL https://github.com/skys-mission/key-agent/releases/latest/download/keyctl-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o keyctl
chmod +x keyctl
sudo mv keyctl /usr/local/bin/

From Source

git clone https://github.com/skys-mission/key-agent.git
cd key-agent
make build
sudo make install

🚀 Quick Start

Option 1: Docker (Fastest)

# 1. Clone and start
git clone https://github.com/skys-mission/key-agent.git
cd key-agent
docker compose up -d

# 2. Get root token from logs
docker logs key-agent | grep "Root token"
# Output: Root token: ka_xxxxxxxx...

# 3. Configure CLI (one-time setup)
keyctl config set addr http://127.0.0.1:8080
keyctl config set token ka_xxxxxxxx...

# 4. Test
keyctl kv set hello world
keyctl kv get hello

Option 2: Binary

Step 1: Start the Daemon

key-agent

On first run, a root token is generated. Save this token!

========================================
Root token generated (save this token):
ka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
========================================

Step 2: Configure CLI

# Configure once, use everywhere
keyctl config set addr http://127.0.0.1:8080
keyctl config set token ka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Verify configuration
keyctl config list

Step 3: Store and Retrieve Values

# Store key-value pairs
keyctl kv set app/database/host "localhost"
keyctl kv set app/database/port "5432"

# Retrieve values
keyctl kv get app/database/host
# Output: localhost

# List all keys
keyctl kv list

Step 4: Store Secrets

# Store an API key
keyctl secret set openai/api_key "sk-xxxxxxxx" --type api_key

# Store a password
keyctl secret set db/postgres/password "mysecretpass" --type password

# Retrieve a secret
keyctl secret get openai/api_key

📖 Usage

Key-Value Operations

# Set a value with metadata
keyctl kv set config/timeout "30s"

# Get raw value only
keyctl kv get config/timeout --raw

# List keys with prefix
keyctl kv list --prefix app/

# Delete a key
keyctl kv delete config/timeout

Secret Operations

# Available secret types: password, api_key, certificate, private_key, token, other
keyctl secret set aws/access_key "AKIAxxxx" --type api_key
keyctl secret set ssh/private_key "-----BEGIN..." --type private_key

# List secrets
keyctl secret list

Token Management

# Create a new token
keyctl token create --name "my-app" --type client --expires-in 24h

# Save token to file
keyctl token save ka_xxxx

🔌 SDK

Key Agent provides a Go SDK for programmatic access:

package main

import (
    "fmt"
    "github.com/skys-mission/keysdk"
)

func main() {
    client := keysdk.NewClient(&keysdk.Config{
        BaseURL: "http://127.0.0.1:8080",
        Token:   "your-token-here",
    })

    // Set a value
    entry, _ := client.SetKV("my-key", &keysdk.SetKVOptions{
        Value: "my-value",
    })
    fmt.Printf("Created: %s\n", entry.Key)

    // Get a value
    entry, _ = client.GetKV("my-key")
    fmt.Printf("Value: %s\n", entry.Value)

    // Store a secret
    secret, _ := client.SetSecret("db-password", &keysdk.SetSecretOptions{
        Value: "super-secret",
        Type:  keysdk.SecretTypePassword,
    })
    fmt.Printf("Secret type: %s\n", secret.Type)
}

🤖 MCP Integration

Key Agent supports the Model Context Protocol (MCP) for AI agent integration. Enable it in your config:

mcp:
  enabled: true
  endpoint: /mcp

Configure your AI assistant to connect to http://localhost:8080/mcp with a valid token.

⚙️ Configuration

Daemon Configuration

File: ~/.skys-mission/key-agent/config.yaml

server:
  addr: 127.0.0.1:8080

storage:
  data_dir: ~/.skys-mission/key-agent/data
  db_name: key-agent.db

security:
  master_key_backend: auto  # auto, keyring, tpm, file

logging:
  level: info
  format: json
  file: ""
  max_size: 100       # MB
  max_backups: 3
  max_age: 30         # days
  compress: true

mcp:
  enabled: true
  endpoint: /mcp

CLI Configuration

File: ~/.skys-mission/key-agent/keyctl.yaml

Configure once, use everywhere:

# Set default server address
keyctl config set addr http://127.0.0.1:8080

# Set default token
keyctl config set token ka_xxxxxxxx...

# Or set token file path
keyctl config set token_file ~/.mytoken

# View current configuration
keyctl config list

Configuration Priority (highest to lowest):

1. Command-line flags: --addr, --token
2. Environment variables: KEY_AGENT_ADDR, KEY_AGENT_TOKEN
3. Config file: ~/.skys-mission/key-agent/keyctl.yaml

Environment Variables:

| Variable | Description | |----------|-------------| | KEY_AGENT_ADDR | Server address (e.g., http://127.0.0.1:8080) | | KEY_AGENT_TOKEN | API token for authentication | | KEY_AGENT_PASSPHRASE | Passphrase for file-based master key |

🛡️ Security

• Encryption: All data is encrypted at rest using AES-256-GCM
• Master Key: Stored securely in OS keyring (Keychain on macOS, Secret Service on Linux)
• Token-based Auth: All API operations require valid tokens
• No Network Exposure: By default binds to localhost only

📚 Documentation

| Document | Description | |----------|-------------| | [User Guide (EN)](docs/USERGUIDE.md) | Detailed usage instructions | | [User Guide (CN)](docs/USERGUIDE_CN.md) | 详细使用指南 | | [API Reference](docs/API.md) | HTTP API documentation | | [Development Guide](docs/DEVELOPMENT.md) | Contributing and development |

🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

# Run tests
make test

# Run linter
make lint

# Build
make build

📄 License

[MIT License](LICENSE)

---

95% Vibe Coding ✨

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skys-mission
• Source: skys-mission/key-agent
• License: MIT

Install and usage instructions live in the source repository linked above.