# 🧑💻 Rune* Developer Guide - Installation & Usage
> **Quick Start**: From Zero to Stack JSON in 60 seconds
---
## 🚀 Installation
### **🦀 Rust (Recommended)**
```bash
# Latest stable
cargo install runeforge
# Specific version
cargo install runeforge --version 25.08.0
# Beta channel
cargo install runeforge --version 25.08.0-beta.1
# Development edge (from Git)
cargo install --git https://github.com/rune-ecosystem/forge runeforge
```
### **🐳 Container**
```bash
# Pull latest stable
docker pull ghcr.io/rune-ecosystem/forge/runeforge:25.08
# Run with mounted blueprint
docker run -v $(pwd):/workspace \
ghcr.io/rune-ecosystem/forge/runeforge:25.08 \
plan -f /workspace/blueprint.yaml
```
### **📥 Binary Download**
```bash
# Linux x64
curl -L https://github.com/rune-ecosystem/forge/releases/latest/download/runeforge-linux-x64 -o runeforge
chmod +x runeforge
# macOS ARM64
curl -L https://github.com/rune-ecosystem/forge/releases/latest/download/runeforge-darwin-arm64 -o runeforge
# Windows x64
curl -L https://github.com/rune-ecosystem/forge/releases/latest/download/runeforge-windows-x64.exe -o runeforge.exe
```
### **🍺 Package Managers**
```bash
# Homebrew (macOS/Linux) - Coming Soon
brew install rune-ecosystem/tap/runeforge
# Scoop (Windows) - Coming Soon
scoop bucket add rune-ecosystem https://github.com/rune-ecosystem/scoop-bucket
scoop install runeforge
# Chocolatey (Windows) - Coming Soon
choco install runeforge
```
---
## ⚡ Quick Start
### **1. Create Blueprint**
```yaml
# my-app.yaml
project_name: "my-awesome-app"
goals:
- "high-performance"
- "low-cost"
- "developer-friendly"
constraints:
monthly_cost_usd_max: 200.0
region_allow: ["us-east-1", "eu-west-1"]
compliance: ["audit-log", "sbom"]
traffic_profile:
rps_peak: 1000.0
global: true
latency_sensitive: false
prefs:
frontend: ["SvelteKit", "Next.js"]
backend: ["Actix Web 4", "Axum"]
database: ["PlanetScale"]
```
### **2. Generate Stack**
```bash
# Basic usage
runeforge plan -f my-app.yaml
# With deterministic seed
runeforge plan -f my-app.yaml --seed 42
# Save to file
runeforge plan -f my-app.yaml --seed 42 --out stack.json
# Strict schema validation
runeforge plan -f my-app.yaml --seed 42 --strict
```
### **3. Use Output**
```bash
# View generated stack
jq '.stack' stack.json
# Pass to RuneWeave (next step)
runeweave deploy --plan stack.json
```
---
## 📋 CLI Reference
### **Commands**
```bash
runeforge plan [OPTIONS] -f <BLUEPRINT>
```
### **Options**
| `-f` | `--file <FILE>` | Blueprint file (YAML/JSON) | **Required** |
| | `--seed <SEED>` | Deterministic seed | `42` |
| `-o` | `--out <FILE>` | Output file | `stdout` |
| | `--strict` | Enable schema validation | `false` |
| `-h` | `--help` | Show help | |
| `-V` | `--version` | Show version | |
### **Exit Codes**
| `0` | Success |
| `1` | Blueprint schema validation failed |
| `2` | Output schema validation failed |
| `3` | No stack matches constraints |
---
## 📝 Blueprint Schema
### **Required Fields**
```yaml
project_name: string # Project identifier
goals: [string] # Objectives ("performance", "cost", etc.)
traffic_profile:
rps_peak: number # Peak requests per second
global: boolean # Global distribution needed
latency_sensitive: boolean # <100ms response time critical
```
### **Optional Fields**
```yaml
constraints:
monthly_cost_usd_max: number # Budget limit
coldstart_ms_max: number # Serverless coldstart limit
compliance: [string] # Required certifications
prefs: # Technology preferences
frontend: [string] # "SvelteKit", "Next.js", "Leptos"
backend: [string] # "Actix Web 4", "Axum", "Express"
database: [string] # "PlanetScale", "Supabase", "Neon"
ai: [string] # "RuneSage", "OpenAI", "Claude"
---
## 🏗️ Examples
### **High-Performance API**
```yaml
project_name: "trading-api"
goals: ["ultra-performance", "low-latency"]
constraints:
monthly_cost_usd_max: 500.0
coldstart_ms_max: 5.0
traffic_profile:
rps_peak: 10000.0
latency_sensitive: true
single_language_mode: "rust"
```
**Output**: Rust + Actix Web + Edge deployment
### **Cost-Optimized SaaS**
```yaml
project_name: "budget-saas"
goals: ["minimal-cost", "rapid-development"]
constraints:
monthly_cost_usd_max: 50.0
traffic_profile:
rps_peak: 100.0
global: false
prefs:
frontend: ["Next.js"]
```
**Output**: Next.js + Serverless + Free tiers
### **Enterprise Compliance**
```yaml
project_name: "healthcare-app"
goals: ["security-first", "compliance"]
constraints:
compliance: ["hipaa", "sox", "gdpr", "audit-log"]
region_allow: ["us-east-1"]
traffic_profile:
rps_peak: 1000.0
```
**Output**: Enterprise-grade stack with audit trails
---
## 🔧 Advanced Usage
### **Custom Rules**
```bash
# Use custom rules file
export RUNEFORGE_RULES_PATH=/path/to/custom-rules.yaml
runeforge plan -f blueprint.yaml
```
### **Environment Variables**
```bash
export RUNEFORGE_LOG_LEVEL=debug # Logging level
export RUNEFORGE_CACHE_DIR=/tmp/rf # Cache directory
export RUNEFORGE_TIMEOUT=300 # Timeout in seconds
```
### **Configuration File**
```yaml
# ~/.runeforge/config.yaml
default_seed: 42
strict_mode: true
output_format: json
cache_enabled: true
log_level: info
```
---
## 🐛 Troubleshooting
### **Common Issues**
**❌ "No candidates match constraints"**
```bash
# Solution: Relax constraints or check regions
runeforge plan -f blueprint.yaml --seed 42 2>&1 | grep -i constraint
```
**❌ "Blueprint schema validation failed"**
```bash
# Solution: Validate against schema
jsonschema -i blueprint.yaml schemas/blueprint.schema.json
```
**❌ "Permission denied"**
```bash
# Solution: Check file permissions
chmod +x runeforge
```
### **Debug Mode**
```bash
# Enable debug logging
RUST_LOG=debug runeforge plan -f blueprint.yaml
# Trace mode (very verbose)
RUST_LOG=trace runeforge plan -f blueprint.yaml
```
### **Support Channels**
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/rune-ecosystem/forge/issues)
- 💬 **Community**: [Discord](https://discord.gg/rune-ecosystem)
- 📚 **Documentation**: [docs.rune.cloud](https://docs.rune.cloud)
- 📧 **Enterprise**: team@rune.cloud
---
## 🔐 Security
### **Signature Verification**
```bash
# Verify binary authenticity
cosign verify-blob \
--certificate-identity="https://github.com/rune-ecosystem/forge/.github/workflows/release.yml@refs/tags/v25.08.0" \
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
--signature=runeforge.sig \
runeforge
```
### **SBOM Analysis**
```bash
# Download SBOM
curl -L https://github.com/rune-ecosystem/forge/releases/latest/download/sbom.json
# Vulnerability scan
grype sbom:sbom.json
syft sbom.json -o table
```
---
> **Next Steps**: Once you have your `stack.json`, proceed to [RuneWeave](https://github.com/rune-ecosystem/weave) for automated deployment!