genie

README

🧞 genie (by Stackgen)

Generative Engine for Natural Intent Execution

"Your intent is my command."

genie is an Enterprise Agentic Platform powered by Stackgen. Describe what you need — across code, operations, security, and beyond — and let genie plan and execute it.

---

✨ Enterprise Differentiators

genie is a platform designed for reliability, compliance, and scale.

• ReAcTree Execution Engine: A deterministic, multi-stage reasoning engine that ensures verifiable plans.
• Agentic Execution: Plans, decomposes, and executes complex multi-step tasks autonomously with sub-agent orchestration.
• Governance & Audit: Built-in Human-in-the-Loop (HITL) guardrails and immutable audit logs ensure strict compliance.
• Multi-Model Routing: Intelligently routes tasks to the best model (OpenAI, Gemini, Anthropic, Ollama, HuggingFace) for cost and performance.
• Enterprise Integrations: Seamlessly integrates with OpsVerse ObserveNow for full-stack observability and Aiden for automated incident response.
• Skills & MCP: Extensible via a file-based skills system and full MCP protocol support.

---

🚀 Get Started

Prerequisites

• Go 1.25+ (only for building from source)
• CGO enabled — required for SQLite via GORM (CGO_ENABLED=1 is set by default on most platforms)

Installation

Homebrew (macOS / Linux):

brew install stackgenhq/homebrew-stackgen/genie

Go install:

CGO_ENABLED=1 go install -mod=mod github.com/stackgenhq/genie@latest

Build from source:

git clone https://github.com/stackgenhq/genie.git
cd genie
make build        # binary at build/genie
make install      # install to $GOPATH/bin

Docker:

docker run --rm -it \
  -v ~/.genie.toml:/home/genie/.genie.toml \
  -v $(pwd):/workspace \
  ghcr.io/stackgenhq/genie:latest grant

GitHub Releases: Download pre-built binaries for macOS, Linux, and Windows from the Releases page.

Windows (Scoop):

scoop bucket add stackgen https://github.com/stackgenhq/homebrew-stackgen
scoop install genie

Grant Your First Wish

Ready to see the magic? Run the interactive wizard:

genie

Or use the explicit command:

genie grant

Deploying on Cloud Instances (EC2, Azure VM, GCP Compute)

Want to run Genie as a shared service for your team? Deploy it on a cloud instance with persistent storage and systemd management.

Option 1: Docker Deployment (Recommended)

# 1. Install Docker on your instance
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 2. Create a config directory
mkdir -p ~/.genie
nano ~/.genie/genie.toml  # Add your configuration

# 3. Run Genie with Docker
docker run -d \
  --name genie \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ~/.genie:/home/genie/.config \
  -v /var/lib/genie/data:/workspace \
  -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
  ghcr.io/stackgenhq/genie:latest grant

Option 2: Binary Installation with Systemd

For EC2 (Amazon Linux / Ubuntu):

# 1. Download and install the binary
curl -L https://github.com/stackgenhq/genie/releases/latest/download/genie_Linux_x86_64.tar.gz -o genie.tar.gz
tar xzf genie.tar.gz
sudo mv genie /usr/local/bin/
sudo chmod +x /usr/local/bin/genie

# 2. Create a genie user
sudo useradd -r -s /bin/false genie
sudo mkdir -p /etc/genie /var/lib/genie
sudo chown genie:genie /var/lib/genie

# 3. Create configuration
sudo nano /etc/genie/genie.toml
# Add your model config, see config.toml.example

# 4. Create systemd service
sudo tee /etc/systemd/system/genie.service > /dev/null <<EOF
[Unit]
Description=Genie Agentic Platform
After=network.target

[Service]
Type=simple
User=genie
Group=genie
WorkingDirectory=/var/lib/genie
Environment="OPENAI_API_KEY=your-key-here"
ExecStart=/usr/local/bin/genie grant --config /etc/genie/genie.toml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 5. Start the service
sudo systemctl daemon-reload
sudo systemctl enable genie
sudo systemctl start genie
sudo systemctl status genie

Security Recommendations

• Use IAM roles (AWS) or equivalent for secret management instead of hardcoded keys
• Configure firewall: Only expose port 8080 to trusted IPs/VPCs
• Enable HTTPS: Use a reverse proxy (nginx/caddy) with Let's Encrypt certificates
• Set rate limits: Configure [agui] rate_limit and max_concurrent in your config
• Regular updates: Set up automated security updates for your instance
• Use cloud secret managers: Configure [security.secrets] for AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault

Example with AWS Secrets Manager:

[security.secrets]
OPENAI_API_KEY = "awssecretsmanager://genie/openai?region=us-east-1&decoder=string"
ANTHROPIC_API_KEY = "awssecretsmanager://genie/anthropic?region=us-east-1&decoder=string"

Nginx reverse proxy example:

server {
    listen 443 ssl http2;
    server_name genie.example.com;

    ssl_certificate /etc/letsencrypt/live/genie.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/genie.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

🛠 Commands

Command	Description
genie or genie grant	Interactive agentic wizard.

---

⚙️ Configuration

genie supports configuration via YAML or TOML files. You can customize model routing, tool access, security policies, and more.

By default, genie looks for .genie.yaml, .genie.yml, genie.yaml, or genie.yml in the current directory, and then falling back to $HOME/.genie.yaml.

You can also specify a config file explicitly:

genie grant --config /path/to/my-config.toml

Environment Variables & Secret Providers

Configuration values matching the pattern ${VAR_NAME} are resolved through the configured SecretProvider:

• Default (env vars): Without a [security] section, placeholders resolve from environment variables — fully backward compatible.
• Cloud / file backends: Add a [security.secrets] section to resolve secrets from GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, mounted files, or any gocloud.dev/runtimevar backend.
• Diagnostics: If a secret-like key (token, api_key, password, etc.) resolves to empty, genie emits a warning pointing to the missing variable name and config path.

See the Security section in the docs for full configuration details.

Example Configuration

Check out config.toml.example for a full example of available options.

[[model_config]]
provider = "openai"
model_name = "gpt-5.2"
token = "${OPENAI_API_KEY}"
good_for_task = "planning"

[[model_config]]
provider = "ollama"
model_name = "llama3"
host = "http://localhost:11434"
good_for_task = "tool_calling"

# Skills: Enable reusable agent capabilities
skills_roots = ["./skills"]  # Paths to skills directories

Skills System

genie supports a skills system based on the agentskills.io specification. Skills are reusable, self-contained capabilities that agents can discover, load, and execute.

Quick Start:

1. Create a skills directory:

   mkdir -p skills/my-skill
   

2. Add a SKILL.md file with YAML frontmatter:

   ---
   name: my-skill
   description: What this skill does
   ---
   
   # My Skill
   
   Detailed instructions...
   

3. Configure in genie.toml:

   skills_roots = ["./skills"]
   

   Or use environment variable:

   export SKILLS_ROOT=./skills
   

Learn More: See docs/skills.md for complete documentation, examples, and best practices.

---

📖 The "Genie" Workflow

1. Rub the Lamp: Call genie (or genie grant).
2. Speak your Intent: Describe what you want to accomplish.
3. Watch the Magic: genie plans, decomposes, and executes using multi-model orchestration.
4. Review & Ship: Approve results through HITL guardrails and deploy with confidence.

Why call it Genie? Because at Stackgen, we believe complex tasks should feel like magic. Just express your intent and consider it granted.

---

🤝 Join the Movement

We are redefining agentic automation. If you want to contribute, check out our contribution guidelines.

1. Fork the repo.
2. Create your feature branch.
3. Submit a PR.

---

📜 Community & Governance

Document	Purpose
Contributing Guide	How to contribute, build, and test
Code of Conduct	Community behavior standards
Security Policy	How to report vulnerabilities
Changelog	Release notes and history
License	Apache License 2.0

---

Built with ✨ by Stackgen. Complex tasks are hard. Being a Genie is easy.

---

Documentation

Overview

Package main is the entry point for genie, the Generative Engine for Natural Intent Execution.

Genie is an enterprise agentic platform. Describe what you need—across code, operations, security, and beyond—and genie plans and executes it using the ReAcTree execution engine, multi-model routing, and integrations (Slack, Discord, MCP, skills, observability). Use the "genie" or "genie grant" command to run the interactive setup; see the repository README for installation and usage.

Copyright © 2026 StackGen, Inc.