Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
SecretForge AI is an AI-powered secret management platform designed to automate the lifecycle of API keys and sensitive credentials. This guide provides a technical overview of how to initialize, configure, and deploy the system within a project environment. The system leverages a local-first approach using SQLite and AES-256-GCM encryption for foundational security, while providing cloud-native integrations via Cloudflare Workers and Model Context Protocol (MCP).
The core philosophy of SecretForge is "Zero Exposed Secrets." It achieves this through automated detection of dependencies in package.json, provisioning of secure keys with optimal scopes, and AI-powered rotation schedules. Sources: README.md:16-25, PHASE1_IMPLEMENTATION.md:9-14
System Architecture Overview
The architecture is a monorepo structure managed by Turborepo, consisting of a CLI, an API (Cloudflare Workers), a Web Dashboard (Next.js), and an MCP Server. Sources: WARP.md:58-65, README.md:99-112
The diagram illustrates the flow from various interfaces (CLI, Web, AI) through the centralized Hono-based API into Cloudflare's edge storage services. Sources: README.md:73-97
Prerequisites
Before setting up SecretForge AI, ensure the following environment requirements are met:
| Requirement | Specification | Source |
|---|---|---|
| Node.js | Version 18+ (20+ recommended) | WARP.md:9, README.md:118 |
| Package Manager | pnpm 8+ | WARP.md:10, README.md:119 |
| Infrastructure | Cloudflare Account | README.md:120 |
| Local Services | Docker and Docker Compose | WARP.md:11 |
| AI Integration | Ollama (Local) or OpenAI/Anthropic Keys | README.md:121-122 |
Initial Setup & Installation
The setup process involves cloning the repository, installing dependencies, and running a specialized launch automation script. Sources: README.md:126-138, scripts/launch.sh:1-10
# Clone the repository
git clone https://github.com/yourusername/secretforge-ai.git
cd secretforge-ai
# Install dependencies and setup environment
pnpm install
cp .env.example .env
# Run launch automation script
bash scripts/launch.sh
The Launch Automation Script
The launch.sh script automates the preparation of packages for npm, builds all project components, and generates marketing materials. It specifically updates the package.json files for the CLI and MCP server with appropriate metadata and dependencies. Sources: scripts/launch.sh:78-95, scripts/launch.sh:110-145
Core CLI Usage
The CLI (sf or secretforge) is the primary interface for local secret management. It operates using a local SQLite database stored in ~/.secretforge/ and requires a SECRETFORGE_ENCRYPTION_KEY. Sources: PHASE1_IMPLEMENTATION.md:105-110, PHASE1_IMPLEMENTATION.md:143-150
Initialization Workflow
The sf init command creates a .secretforge.json configuration file and initializes the local encrypted database. Sources: PHASE1_IMPLEMENTATION.md:78-82, SYSTEM_EVALUATION.md:162-163
Managing Secrets
- Add:
sf add [NAME]adds an encrypted secret interactively. Sources: PHASE1_IMPLEMENTATION.md:84-88 - List:
sf listdisplays metadata and masked values. Sources: PHASE1_IMPLEMENTATION.md:90-94 - Inject:
sf inject --env devdecrypts secrets and populates a.env.devfile. Sources: PHASE1_IMPLEMENTATION.md:96-101 - Export:
sf export --format jsonoutputs decrypted secrets for CI/CD pipelines. Sources: PHASE1_IMPLEMENTATION.md:103-108
Model Context Protocol (MCP) Integration
SecretForge includes an MCP server that allows AI assistants like Claude Code to manage secrets directly. The MCP server exposes tools for project analysis and secret provisioning. Sources: packages/mcp-server/src/index.ts:31-41, README.md:195-207
Available MCP Tools
| Tool Name | Description | Input Parameters |
|---|---|---|
analyze_project | Detects required API keys in package.json | projectPath |
create_secret | Provisions a new API key for a service | service, environment, scopes |
rotate_secret | Rotates an existing API key | secretId |
validate_security | Checks compliance (SOC2, GDPR, etc.) | secretId, framework |
Sources: packages/mcp-server/src/index.ts:48-124
MCP Logic Flow
The MCP server uses a detectServices function to map project dependencies to known API providers like Stripe, OpenAI, and AWS. Sources: packages/mcp-server/src/index.ts:251-270
Security Implementation
SecretForge uses AES-256-GCM for all secrets at rest. Every encryption operation generates a random 12-byte Initialization Vector (IV) and a 128-bit authentication tag to ensure data integrity. Sources: SYSTEM_EVALUATION.md:87-105, PHASE1_IMPLEMENTATION.md:46-56
- Algorithm: AES-256-GCM (NIST approved). Sources: SYSTEM_EVALUATION.md:88
- Key Source:
SECRETFORGE_ENCRYPTION_KEYenvironment variable. Sources: PHASE1_IMPLEMENTATION.md:52 - ID Generation: Uses
crypto.randomUUID()for cryptographically secure, unpredictable identifiers. Sources: SYSTEM_EVALUATION.md:144-148
Summary
The SecretForge AI Quick Start Guide establishes a secure, local-first foundation for secret management while providing the necessary bridges to AI assistants and cloud infrastructure. By following the installation and initialization steps, developers can move away from unencrypted .env files to a system that provides automated detection, encryption, and rotation of sensitive credentials. The integration of MCP and Cloudflare Workers ensures that this security model scales from local development to global edge production. Sources: PHASE1_IMPLEMENTATION.md:209-222, README.md:255-265