FreeAgent

Your AI. Your hardware. Your rules.

---

FreeAgent is a local-first AI agent with 60+ tools that runs entirely on your own hardware. Image generation, OSINT, cybersecurity scanning, email automation, system administration — all from a single interface, all under your control.

No subscriptions. No cloud dependency. No data leaving your machine. No censorship.

---

The Problem

Cloud AI agents want your money, your data, and your obedience. They charge hundreds per month, route everything through their servers, and decide what you're allowed to do with your own tools. Some have known CVE vulnerabilities while handling your data.

The Solution

FreeAgent runs on your machine with your models. It's free, it's private, and it doesn't answer to anyone but you. Plug in a cloud provider when you want more power — or don't. Everything works locally out of the box.

	FreeAgent	Cloud AI Agents
Cost	Free forever	$200+/month
Your data	Never leaves your machine	Stored on their servers
Censorship	None — your models, your rules	Filtered and restricted
API keys	Optional	Required
Internet	Optional	Required
Tools	60+ and growing	Whatever they let you use

---

Quick Start

Get running in under 5 minutes:

git clone https://github.com/transformer24/freeagent.git
cd freeagent
python3 -m venv venv && source venv/bin/activate
pip install requests chromadb ollama
python3 server.py

Open http://localhost:5000 — that's it.

Note: You need Ollama installed with at least one model pulled. If you don't have one yet:

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3

---

What's Inside: 60+ Tools

AI Image Generation

Powered by ComfyUI — runs on your GPU, no cloud APIs.

Tool	What it does
text2img	Generate images from text prompts
img2img	Transform existing images with AI guidance
faceid	Face-consistent generation with IPAdapter
inpaint	Region-based inpainting with automatic mask detection

OSINT & Reconnaissance

All free-tier compatible. No paid subscriptions needed.

Tool	What it does
holehe	Check if an email is registered on 120+ sites
theharvester	Extract emails and subdomains from any domain
shodan_host	IP and device intelligence lookup
shodan_search	Search Shodan's device database
spiderfoot	Multi-target automated OSINT
reconng	Domain reconnaissance framework

Cybersecurity

Tool	What it does
nmap_scan	Port and service discovery
nikto_scan	Web server vulnerability scanning
sqlmap_scan	SQL injection detection
dirb_scan	Directory and file brute-forcing
whatweb_scan	Web technology fingerprinting
sslyze_scan	SSL/TLS configuration audit

Email Automation

Draft-review-send workflow so nothing goes out without your approval.

Tool	What it does
draft_email	Create a draft for review
send_draft	Send after you approve
send_email	Direct send via Gmail SMTP
lookup_reps	Find your elected representatives by address

System Administration

Full control over your machine from natural language.

• Disk, memory, CPU, GPU, and temperature monitoring
• Service management — start, stop, restart, status
• Process listing and killing
• Network info, open ports, public IP, Wi-Fi details
• Docker containers and images
• Cron jobs, package installation (pip and apt)
• File operations — read, write, list, delete, compress, extract
• Git status and history

Web & Utilities

• Web search via DuckDuckGo (no API key needed)
• Web fetch — grab any page content
• Shell execution — run any command
• Ollama management — list and manage local models
• Date/time — current system time

---

Architecture

freeagent/
├── server.py              # Flask web server
├── telegram_bot.py        # Telegram bot interface
├── config.json            # Model routing and provider config
├── core/
│   ├── agent.py           # Brain — intent routing, memory, tool dispatch
│   ├── tools.py           # All 60+ tools
│   ├── paths.py           # Dynamic path resolution (no hardcoded paths)
│   ├── image_gen.py       # Text-to-image pipeline (ComfyUI)
│   ├── img2img.py         # Image-to-image pipeline (ComfyUI)
│   ├── faceid.py          # FaceID generation (ComfyUI + IPAdapter)
│   └── inpaint.py         # Inpainting pipeline (ComfyUI)
├── web/
│   └── index.html         # Dark-themed web UI
└── workspace/
    ├── IDENTITY.md        # Agent identity config
    └── SOUL.md            # Agent personality and behavioral rules

Key design decisions:

• Multi-provider model routing — Ollama (local/free), OpenAI, Anthropic, Groq, xAI. Switch with one config change.
• ChromaDB persistent memory — Agent remembers across sessions.
• Intent router — Natural language triggers the right tool automatically.
• No hardcoded paths — Dynamic resolution via paths.py so it runs on any system.

---

Interfaces

Web UI — Dark-themed interface at localhost:5000 with tool toggles, model selection, and markdown rendering.

Telegram Bot — Full agent access from your phone, including image generation and inpainting workflows.

---

Configuration

config.json

FreeAgent supports multiple AI providers. Ollama (local, free) is the default.

{
    "default_provider": "ollama",
    "default_model": "huihui_ai/deepseek-r1-abliterated:latest",
    "providers": {
        "ollama": { "base_url": "http://localhost:11434" },
        "openai": { "base_url": "https://api.openai.com/v1", "api_key": null },
        "anthropic": { "base_url": "https://api.anthropic.com", "api_key": null },
        "groq": { "base_url": "https://api.groq.com/openai/v1", "api_key": null }
    }
}

.env (optional)

Only needed if you want email, Telegram, or Shodan tools:

GMAIL_USER=your_email@gmail.com
GMAIL_APP_PASSWORD=your_app_password
HOME_ADDRESS=your_address
SHODAN_API_KEY=your_key
TELEGRAM_TOKEN=your_token

---

Requirements

Component	Minimum	Recommended
OS	Ubuntu 22.04	Ubuntu 24.04
GPU	Any NVIDIA w/ CUDA	RTX 3090 24GB
RAM	16GB	64GB+
Python	3.10+	3.12
Storage	20GB free	100GB+ (for models)

Required: Ollama for local model inference.

Optional:

• ComfyUI — for image generation tools
• Gmail App Password — for email tools
• Shodan API key — for Shodan tools (free tier works)

---

Troubleshooting

"Ollama not found" or model errors Make sure Ollama is running: ollama serve in a separate terminal, then ollama list to verify your models.

Image generation not working ComfyUI must be running before using image tools. Start it first, then FreeAgent.

Email tools failing You need a Gmail App Password (not your regular password). Go to Google Account → Security → 2-Step Verification → App Passwords.

Permission errors on Linux Some security tools (nmap, nikto) may need sudo. Run FreeAgent with appropriate permissions or configure sudoers.

Out of VRAM If you're running large models + ComfyUI simultaneously, you may run out of GPU memory. Check usage with nvidia-smi and close one if needed.

---

Roadmap

• Docker support (one command to run on Windows, Mac, and Linux)
• Skill/plugin system — community-contributed tools without editing core code
• One-click installer script
• WhatsApp integration
• Discord integration
• Voice interface
• Multi-agent collaboration
• Mobile app

---

Built With

• Ollama — Local model inference
• ComfyUI — Image generation backend
• ChromaDB — Persistent vector memory
• Flask — Web server
• DuckDuckGo — Web search (no API key)
• holehe — Email OSINT
• theHarvester — Domain reconnaissance
• SpiderFoot — OSINT automation
• Shodan — Device intelligence

---

Contributing

Pull requests welcome. Found a bug? Open an issue. Built a new tool? Submit a PR.

If you build something cool with FreeAgent, show it off in the Discussions tab.

---

License

MIT — use it, fork it, sell it, whatever. It's yours.

---

Run local. Run free. Own your AI.