Open-source AI agents that work the plan.
Give Gantrix a goal and a team of agents with skills. It plans the work as steps that depend on each other, runs whatever is ready in parallel, checks every result, and keeps going until the goal is met. It runs entirely on your machine, with open-source models.
See it
A team of agents you can watch and steer
The dashboard runs on your machine. These screenshots are from a demo with a made-up bakery.
Get started
Your first task in about 10 minutes
Most of the time is the model download. Everything runs on your laptop; nothing leaves it.
| You need | Check with | Get it |
|---|---|---|
| Node.js 26.13 or newer | node -v | nvm install (the repo has an .nvmrc) |
| Docker, running | docker info | Docker Desktop or OrbStack |
| Ollama, running | ollama list | ollama.com; on a Mac run it natively, not in Docker, so it can use the GPU |
- 1
Install and configure
Fastest:
./init.shinstalls nvm and the right Node, runsnpm install, starts Postgres and Valkey, migrates, and starts the API, worker and dashboard. Docker must be running. Prefer to do it by hand? The commands are below;npm run setupcreates.envwith a random API token.git clone git@github.com:PerDiemInc/gantrix.git && cd gantrix ./init.sh
git clone git@github.com:PerDiemInc/gantrix.git && cd gantrix nvm use npm install npm run setup npm run infra:up # Postgres :15432, Valkey :16379 npm run db:migrate ollama pull qwen3:8b # the default model, about 5 GB
- 2
Start Gantrix
npm startruns all three together. Or use three terminals, one command each; the worker prints “Gantrix worker ready”.npm start # or the three commands below npm run dev:api # API on 127.0.0.1:4700 npm run dev:worker # runs plans, steps and judges npm run dev:web # dashboard on 127.0.0.1:4701
- 3
Open the dashboard
Go to
http://127.0.0.1:4701and paste your token once. Print it with:npm run token
- 4
Add a skill and two agents
The planner reads each agent's description to decide who does what, so make it specific.
npm run gantrix -- skills add examples/skills/workspace-files npm run gantrix -- agents add researcher -d "Collects facts and writes notes" -s workspace-files --max-concurrency 2 npm run gantrix -- agents add editor -d "Turns notes into a polished summary" -s workspace-files
- 5
Run a task
You see the plan, each step start and finish, and a Gantt chart at the end. Or follow it on the dashboard.
npm run gantrix -- run "Write tea.md and coffee.md with 3 facts each, then compare.md with a table" npm run gantrix -- files last compare.md
| If you see | Do this |
|---|---|
| Can't reach the Gantrix API | Start npm run dev:api. |
| The API rejected the token | The CLI reads the repo's .env. In the dashboard, choose Forget token and paste npm run token again. |
| A task stays at planning | Start npm run dev:worker. |
| Steps fail with a model error | Start Ollama and run ollama pull qwen3:8b. |
| port is already allocated | Something else uses 15432 or 16379. Stop it, or change the ports in docker-compose.yml and .env. |
How it works
Plan, run, judge, repeat
Every task goes through the same loop. The state lives in Postgres, so you can stop and restart the worker at any point and the task picks up where it was.
- 01 · plan
Split the goal
The planner reads the goal and your agents' descriptions and returns steps with dependencies. Bad plans go back to it with the errors.
- 02 · schedule
Start what's ready
Every step whose dependencies are done starts, within each agent's limit and the worker's model slots.
- 03 · run
Do the work
The step's agent uses its skills' tools in the task's own folder, up to 25 model turns.
- 04 · judge
Check the result
A judge compares the reply and the files written against the step's “done when”. Rejected steps retry with the feedback.
- 05 · replan
Change course
A step that keeps failing triggers a new plan that keeps the finished work and routes around the problem.
- 06 · finish
Check the goal
When every step passes, the judge checks the goal itself. Budgets for tokens, time and replans stop runaway tasks.
Many projects, one screen. Every project shows its progress, its agents and what they're doing right now. Open one for its Gantt timeline, a card per busy agent and a chat where the planner, agents and judge talk in turn. Send a note to one agent mid-task, or to everyone to change the plan; finished work is kept.
Nothing is hidden. Each project's Logs page shows every task's full conversation: the instructions, the agent's replies, each tool call with its result, and the judge's verdict, next to the live event log. In the terminal, run gantrix logs last.
Skills
A skill is a folder with a SKILL.md
Plain Claude skills work as they are. Gantrix reads a few extra keys: which built-in tools the agent may use, MCP servers to start, and which tools can run without asking.
Installing a skill copies it and records a checksum, so editing your original folder never changes what runs. Bump the version to update it.
| Built-in tool | Does | Approval |
|---|---|---|
read_file write_file list_files | Text files in the task's folder only | never |
web_fetch | Public web pages; local and private addresses refused | asks |
shell | A command in the task's folder, 2-minute limit | always |
---
name: web-researcher
description: Finds and summarises sources on the web.
version: 1.0.0
tools: [web_fetch, write_file]
mcp-servers:
search: { command: npx, args: [-y, some-search-mcp] }
auto-approve: [web_fetch]
---
Fetch only the pages you need. Record the URL
of every source next to the notes you take.Try it
"Build me a website"
An example project where the agents talk to you. The product manager asks what the site is for and who it's for. The designer sketches three styles and asks which one you like. The engineer builds the site in that style and deploys it to a preview link on your machine.
- Agents ask, you answer. Questions appear on the project page with one-click answers, or answer in the terminal.
- You pick the look. The designer's question shows a live preview of each style, and the project's gallery shows every mockup and image (PNG, JPEG or WebP).
- Agents with sub-agents. The DevOps lead ships to Supabase, Heroku, Vercel or Fly.io itself, and hands AWS and GCP Terraform to its own AWS and GCP engineers.
- Talk to it in Slack. Each project gets a Slack thread with its progress. Reply to steer the team or answer their questions, or ask the app what's left.
- You set the limits. Describe the project, set an OKR (or let the model draft one), choose the team and each member's model, and how long they get.
- A team and a board. See which employee works on which task, edit any task or reassign it, and give each agent its own model, including Claude Code.
- Deployed locally. The finished site is served at
127.0.0.1:4702, on its own port, away from your dashboard.
npm run gantrix -- team add npm run gantrix -- example website
Built-in team
A C-suite of agents in one command
Optional. gantrix team add installs ten agents with their own skills, so one goal can be split across engineering, deployment, marketing, sales, security, product and design.
| Agent | Does |
|---|---|
cto | Architecture decisions, code reviews, build plans and technical risks |
cmo | Positioning, campaign plans, launch posts and SEO briefs |
cro | Lead lists, cold email and SMS drafts, and one-to-one email |
ciso | Threat models, code and dependency audits, tests of systems you own |
cpo | PRDs, priorities and milestone timelines with owners and dates |
engineer | Builds websites and small tools, and deploys them to the local preview server |
devops | Ships to Supabase, Heroku, Vercel, Netlify, Render, Fly.io, Railway or Cloudflare, and delegates AWS and GCP to its sub-agents |
aws-engineer | Sub-agent: Terraform for AWS, checked and planned; applies only after your yes |
gcp-engineer | Sub-agent: Terraform for GCP (Cloud Run, Cloud SQL, CDN), checked and planned; applies only after your yes |
designer | Mobile apps, websites, dashboards, marketing materials, business cards and Google Slides decks |
- Email with guardrails. Every CRO email waits for your approval, even with approvals off, and carries an unsubscribe line and your postal address.
- No spam by design. There's a daily cap, at most three emails per person, a do-not-contact list that also covers +tags and subdomains, and SMS stays draft-only.
- Decks land in Google Slides. The designer builds them in your Drive with access only to the decks it creates.
- Every agent has a face. Each one gets a Gant avatar you can swap for another, or for your own picture.
- Security stays in scope. The CISO tests only what you name as yours, and every shell command asks first.
npm run gantrix -- team add npm run gantrix -- run "CPO: plan the v2 launch; CTO: estimate the work; CMO: write the launch post"
Images and video
Agents that make images and clips, locally
Optional. Give an agent the media skills and it can create PNG images and short MP4 clips with open models running in a local ComfyUI. Every model is Apache-2.0, and nothing leaves your machine.
| Model | Makes | On a 48 GB M5 Pro |
|---|---|---|
z-image-turbo | Images from text, or variations of an image | about 30 s |
wan-2.2-5b | 2–20 s clips from text or a start image | 2 s clip: 1.5 min fast, 3.5 min standard, 12 min high |
- You choose the models per skill; agents pick among them per call.
- Video takes minutes. A 2 s clip renders in about 3.5 minutes at standard quality.
- RAM is freed after every job. Models unload when nothing is generating.
- Not open source? You'll know. Any such model shows a warning with its usage limits and stays off until you opt in.
npm run comfyui:setup -- all # ComfyUI + models, about 43 GB
cd ~/ComfyUI && .venv/bin/python main.py --listen 127.0.0.1 --port 8188
npm run media:link
npm run gantrix -- skills add examples/skills/media-images
npm run gantrix -- skills add examples/skills/media-video
npm run gantrix -- agents add artist -d "Creates images and short video clips" -s media-images,media-videoJobs and chat in Slack
A job is a saved list of steps: this agent does this, then that agent does that. Run it on demand or on a cron schedule such as every weekday at 09:00. Each run shows up as a project you can follow and steer. Press + New Job on the Projects page, or use gantrix jobs.
Give an agent a Slack connection (bot token, app-level token and the people allowed to talk to it) and you can DM it or mention it in a channel: @Gantrix writer: summarize what we shipped.
Safety
You stay in the loop
- Approvals when you want them. Agents run every tool on their own by default. Turn on Ask me before risky tools, or use
--ask, and shell, web, MCP and email calls wait; only that step pauses. - Shell isn't sandboxed. It can do anything your user account can. Without approvals, give agents shell only for goals and skills you trust.
- Everything is logged. Every tool call shows in the project's chat and Logs page, approved or not.
- Web pages can talk back. Fetched text can try to steer an agent. It can only hand work to agents on the project's team, web fetches can't reach private addresses, and approval is where you catch the rest.
- Local only. The API listens on 127.0.0.1, needs your token on every request and answers only to localhost, so a web page can't reach it by rebinding its domain. Tokens are never accepted in URLs.
- No secrets for tools. Shell commands, MCP servers and local Claude or ChatGPT runs don't get the server's environment, so they can't read API keys, the token or the database password.
- Confined files. File tools can't leave the task's folder, through
.., absolute paths or symlinks. - Separate folders per step (optional). With
GANTRIX_ISOLATED_STEPS=trueeach step works in its own folder with copies of what it builds on, so agents can't overwrite each other's files. It isn't a sandbox for shell. - Measure it.
npm run evaluateruns two small business workflows on your model and checks the results independently of the judge.
Models
Local by default. Any model when you want it.
Agents run on Ollama out of the box. Save a connection to give any agent OpenAI, Anthropic, or anything that speaks their APIs: vLLM, llama.cpp, LM Studio, LiteLLM, OpenRouter or your own gateway. Each agent can use a different one.
- Any HTTP server. Set the URL, method, headers, Content-Type, the body with your prompt in it, and where the reply is. Test it before an agent uses it.
- Keys stay in your environment. Write
env:OPENAI_API_KEYand the worker reads it when a step runs. The API never returns header values. - Offload to Claude or ChatGPT. One switch runs a project's agents on Claude Code or the Codex CLI on your machine, with your own login.
gantrix run --offload chatgptdoes the same. - Your Claude Code as an agent. A
claude-codeconnection runsclaude -pin the project's folder; on projects that ask first it gets file tools only. - Cloud is labelled. A connection that leaves your machine is marked cloud, so you know where task content goes.
npm run gantrix -- connections add claude --provider anthropic --api-key-env ANTHROPIC_API_KEY npm run gantrix -- connections test claude claude-sonnet-5-5 npm run gantrix -- agents add writer -s workspace-files -c claude -m claude-sonnet-5-5
Live
See which agents and local models are running
The dashboard's Live page answers “what is my machine doing right now?” in one screen. It refreshes every 3 seconds and reads only from your own machine.
- Every agent at work. The task and project it is on, how long it has been at it, the tokens it has used, and whether it is working, being judged or waiting for you.
- The model behind each agent. The model name and where it runs: Ollama, your own server, Claude Code or a cloud API.
- Local or cloud, at a glance. A count of the agents sending prompts off your machine. With the defaults it reads zero.
- Models loaded in Ollama. Each model in memory with its size, GPU or CPU split, context length, the agents using it and when Ollama unloads it.
- Stopped means stopped. A project you stop drops off the page; its work is kept for when you resume.
Next to it, the System page shows memory, CPU load and every running Docker container. New to local models? Read how to run AI agents locally with Ollama.
Built with
Open source, top to bottom
FAQ
Questions people ask
What is Gantrix?
Gantrix is an open-source, local-first AI agent orchestrator. You give it a goal and a team of agents with skills. It plans the goal as steps that depend on each other, runs the ready steps in parallel, has a judge check every result, and retries or replans until the goal is met or a budget runs out.
Does my data leave my machine?
Not by default. Agents run on Ollama models on your machine, state lives in a local Postgres, and the API listens on 127.0.0.1 only. Task content leaves your machine only if you add a cloud connection such as OpenAI, Anthropic or Claude Code, or give an agent the web_fetch tool. Cloud connections are labelled cloud in the dashboard.
Which models does Gantrix work with?
Ollama out of the box; the default model is qwen3:8b. You can also connect OpenAI, Anthropic, and anything that speaks their APIs: vLLM, llama.cpp, LM Studio, LiteLLM, OpenRouter or your own gateway. One switch runs a project on Claude Code or the Codex CLI with your own login. Each agent can use a different model.
What do I need to run it?
Node.js 26.13 or newer, Docker for Postgres and Valkey, and Ollama, on macOS or Linux. The default model is about a 5 GB download, and the first task takes about 10 minutes to set up.
How do I see which agents and models are running?
Open the Live page in the dashboard. It lists every agent working right now, the task and project it is on, the model it runs on, and whether that model is local or cloud. Below it are the models Ollama holds in memory: size, GPU or CPU, which agents use each one, and when it unloads.
How is Gantrix different from CrewAI or LangGraph?
CrewAI and LangGraph are frameworks you build agent systems with in code. Gantrix is a ready-to-run app: API, worker, web dashboard and CLI. A planner writes the plan for you, steps run in parallel, and a judge checks each one. Gantrix is built on LangGraph.js. See Gantrix vs CrewAI and Gantrix vs LangGraph.js.
Can agents run shell commands, and is that safe?
Only agents whose skills include the shell tool can. Shell is not sandboxed: it can do anything your user account can. Turn on Ask me before risky tools and every shell, web, MCP and email call waits for your approval. Shell commands and MCP servers never get the server's environment, so they cannot read your API keys.
Is Gantrix free?
Yes. Gantrix is MIT licensed and built on open-source software. Running it on local models costs nothing but your own hardware.
Read more
Guides and comparisons
- Run AI agents locally with Ollama. What you need, the five steps, and how to see what is running.
- Gantrix vs CrewAI. A ready-to-run TypeScript app next to a mature Python framework.
- Gantrix vs LangGraph.js. What an orchestrator adds on top of the library it is built on.