Hephaestus: Local-First, Open-Source AI Agents That Train ML Models While You Go Outside

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

Hephaestus is a local-first, autonomous coordinator for machine learning pipelines. You describe a model in plain language, for example "train a CNN to classify these images", and a team of AI agents takes it from there: they read the research, find a dataset, write the PyTorch code, run the training in a sandbox, fix their own bugs, and remember what worked for next time.

How it gets people off the screen. This isn't a hiking app, and I won't pretend it is. The "grass" here is the hours that ML engineers spend babysitting: hunting for papers, reading shape-mismatch tracebacks, re-running a script that died on a missing import, and watching a GPU in case it runs out of memory. Hephaestus is built so the human's screen time is the shortest part of the job. You write one prompt, the agents run the whole loop unattended (research, data, code, training, debugging), and the dashboard exists to be glanced at, not stared at. When a run finishes, the best scripts are saved as reusable skills, so the next run starts further along.

Who it's for: students and researchers who have a GPU and a deadline, and who would rather go outside than debug tensor dimensions. It's also for anyone who wants an agent system that keeps code, data and API keys on their own machine.

Hephaestus is local-first by design, so it runs on your own machine instead of at a public URL, which keeps your data and keys off any server you don't control. You can start it in four commands (Docker is required, plus Ollama for local models):

cp.env.example.env docker compose up -d redis mongodb searxng cd backend && uv sync && uv run python main.py # API on:8000 cd frontend && pnpm install && pnpm dev # dashboard on:3000 Enter fullscreen mode Exit fullscreen mode Then open http://localhost:3000. The dashboard shows a live GPU memory graph, a streaming terminal of the training logs, and a multi-agent chat where each message is tagged with the agent that sent it (Research, MLOps, Orchestrator). The repo README has the full setup for both native and full-Docker modes.

Follow these steps to spin up the entire Hephaestus stack locally using Docker Compose.

First, create a.env file from the example template:

cp.env.example.env # macOS / Linux copy.env.example.env # Windows (cmd / PowerShell) Enter fullscreen mode Exit fullscreen mode Open the.env file and set the required variables (like SEARXNG_SECRET ).

Run the following command from the root of the project to build the images and start the services in detached mode:

docker compose up --build -d Enter fullscreen mode Exit fullscreen mode This will spin up: