# Key Agent

> Local sensitive information agent daemon and CLI for secure secret storage, key management, and MCP-style access control in Go.

- **Type:** MCP server
- **Install:** `agentstack add mcp-skys-mission-key-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [skys-mission](https://agentstack.voostack.com/s/skys-mission)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [skys-mission](https://github.com/skys-mission)
- **Source:** https://github.com/skys-mission/key-agent

## Install

```sh
agentstack add mcp-skys-mission-key-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

🔑 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](https://modelcontextprotocol.io/)
- 🖥️ **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)

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

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

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

## 🚀 Quick Start

### Option 1: Docker (Fastest)

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

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

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

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

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

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

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

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

```go
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)](https://modelcontextprotocol.io/) for AI agent integration. Enable it in your config:

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

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

```bash
# 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/USER_GUIDE.md) | Detailed usage instructions |
| [User Guide (CN)](docs/USER_GUIDE_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.

```bash
# 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](https://github.com/skys-mission)
- **Source:** [skys-mission/key-agent](https://github.com/skys-mission/key-agent)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-skys-mission-key-agent
- Seller: https://agentstack.voostack.com/s/skys-mission
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.