# TheYgent

> TheYgent is a no-code, local-first platform for building and running AI agents on a visual canvas. Inference runs on the user's own machine — llama.cpp, MLX, or vLLM — or on any OpenAI-compatible API they register, chosen per agent and per call. It is source-available fair-code software under the Sustainable Use License, self-hosted on bare metal, Docker Compose, or Kubernetes. The core promise: you own every hop.

Key facts:

- The graph is the agent: drag nodes onto a canvas, wire them with edges, configure them in an inspector, and run — no code required. Node types include input, llm, tool, mcp, rag, crawler, router, transform, guardrail, human (approval), subgraph, loop, map, ratelimit, quota, transcribe, speak, imagine (image generation), and output.
- Models are addressed by a logical ID (for example `triage-fast`); the engine underneath — `mlx`, `vllm`, `llamacpp`, or `openai-compatible` — can be swapped without touching the graph. One graph can mix local and hosted models side by side.
- TheYgent is never an involuntary middleman between users and their models: prompts, payloads, and model weights are not proxied through the vendor's servers. Hosted APIs can be registered at any time; when data crosses the wire, it does so because the user sent it there.
- Local inference is built in: the inference plane installs models from an in-app Hugging Face catalog (each variant shows whether it fits the machine's RAM) and starts, warms, and unloads its own engines — llama.cpp on any machine, MLX on Apple Silicon, vLLM (experimental) on NVIDIA GPUs. There is no separate model server to install or run. Modalities: chat, vision, embeddings, speech-to-text, text-to-speech, and image generation.
- Models bigger than memory: on Apple Silicon, the MLX engine can run a mixture-of-experts model whose weights don't fit in memory, keeping the shared part loaded and reading each layer's chosen experts from the SSD with a memory cache. Answers are token-for-token identical to the fully loaded model; measured on a 36 GB Mac, Qwen3.6-35B-A3B (20 GB) ran at 53 tokens/s fully loaded and 4–9 tokens/s in 1.8–5.7 GB from a cold SSD. Off by default, set per model.
- Privacy: no telemetry, usage analytics, crash reporting, update checks, or license activation, and no vendor account. Once installed, TheYgent runs fully offline or air-gapped. Its only automatic outbound request is a public model price list that the inference plane's model client library (LiteLLM) fetches at startup; it carries no user data and falls back to a bundled copy when offline. Hugging Face, MCP registries, and the Apify Store are contacted only when the user browses them.
- Human-in-the-loop: a human approval node pauses a run until someone approves or rejects; approvals run on the durable runtime, so a pending approval survives restarts.
- Tooling: built-in tools, HTTP tools, and any MCP (Model Context Protocol) server over stdio or HTTP, plus autonomous LLM tool-calling wired visually on the canvas.
- Coding agents: TheYgent ships an MCP server, so Claude Code, Codex, OpenCode, or any MCP client can offload prompts and local files to the user's own models, run and build TheYgent agents, and index and search docs and code. Model calls go from the MCP server straight to the user's inference plane; agent runs and searches use a personal API key against the user's control plane.
- Retrieval: crawl a site or upload documents, embed them locally into pgvector, and wire RAG retrieval into any graph.
- Crawler nodes (new in 1.3): browse the Apify Store from the editor and install a hosted scraper or crawler as a node, run as a step or as a tool a model calls. The builder chooses which fields the model fills; everything else is fixed on the node. Every run carries a charge cap held under a platform ceiling, and the model reads a trimmed result. Apify runs the actors on its own servers and bills the user's Apify account.
- Automation: deploy a saved agent behind a token-authenticated endpoint, an HMAC-signed webhook (`X-TheYgent-Signature`), or a cron schedule.
- Production discipline: durable runs checkpoint every step and resume after a crash (including loops, subgraphs, and human approvals); every run yields a span waterfall with per-node inputs, outputs, timing, and token usage; opt-in OTLP export to any OpenTelemetry collector; agents are immutable, content-addressed versions; runs, sessions, and traces persist in the user's own Postgres.
- AI Gateway (new in 1.0): an optional service the user runs between Claude Code and the Anthropic API to cut what Claude Code costs. Observer mode records every exchange (its cost, its kind of request: main conversation, subagent, compaction or side request, and what routing would have saved) without changing it. Router mode moves subagents and cold-cache turns to a cheaper Claude model, and a share the user chooses to models on their own inference plane, each measured on the user's own traffic first. It runs on the user's machine or cluster, personal (loopback, no keys) or team (per-developer gateway keys); the control plane receives metadata only, never prompt or response text.
- Quickstart: `git clone https://github.com/al2m4n/TheYgent.git && cd TheYgent && cp .env.example .env && make up` brings up four local services (interface :5174, control plane :8080, inference plane :8081, AI Gateway :8082). No vendor account or cloud sign-up — the only account is the local admin created in the first-run wizard; localhost by default.
- License: the Sustainable Use License (fair-code). Free to use, modify, and self-host for internal business, personal, and non-commercial purposes; selling it — including offering it as a hosted service — is not permitted.

## Docs

- [Documentation home](https://docs.theygent.ai/latest/): start here — installation, concepts, and guides
- [Installation](https://docs.theygent.ai/latest/getting-started/installation/): prerequisites and setup for macOS and Linux
- [Your First Agent](https://docs.theygent.ai/latest/getting-started/first-agent/): build and run an agent on the canvas
- [Concepts: Agents & Graphs](https://docs.theygent.ai/latest/concepts/agents-and-graphs/): how a graph becomes an agent
- [Concepts: Models & Engines](https://docs.theygent.ai/latest/concepts/models-and-engines/): logical model IDs and the engine bindings (mlx, vllm, llamacpp, openai-compatible)
- [Node Reference](https://docs.theygent.ai/latest/building/nodes/): every node type — LLM, tools, MCP, RAG, crawler, router, transform, guardrail, rate limit and quota, human approval, subgraph/loop/map, audio and images
- [MCP](https://docs.theygent.ai/latest/mcp/): using Model Context Protocol tools and servers
- [The Crawler Node](https://docs.theygent.ai/latest/building/nodes/crawler/): hosted Apify actors as steps or model tools — the Crawlers browser, exposed fields, fixed input, spend caps, result budgets, and long crawls on durable runs
- [Apify Through the MCP Hub](https://docs.theygent.ai/latest/mcp/apify/): Apify's MCP server installed from the hub, choosing actors with `?tools=`, and when a crawler node fits better
- [RAG](https://docs.theygent.ai/latest/rag/): retrieval sources, crawling, and document upload
- [Durable Runs](https://docs.theygent.ai/latest/running/durable/): crash-resumable execution
- [Triggers & Webhooks](https://docs.theygent.ai/latest/running/triggers/): token endpoints, HMAC-signed webhooks, cron schedules
- [Observability](https://docs.theygent.ai/latest/running/observability/): run waterfalls and OTLP export
- [AI Gateway](https://docs.theygent.ai/latest/ai-gateway/): observe, route and cut what Claude Code costs; personal and team gateways
- [AI Gateway: Local Models](https://docs.theygent.ai/latest/ai-gateway/local-models/): serving a share of Claude Code's requests with models you run, measured by trials first
- [Use TheYgent from Coding Agents](https://docs.theygent.ai/latest/coding-agents/): the MCP server — connect Claude Code, Codex, or OpenCode to offload work to local models, run and build agents, and search docs and code
- [Coding Agents: Tools & Recipes](https://docs.theygent.ai/latest/coding-agents/tools/): every MCP tool, prompts that work well, and a project-instructions snippet
- [API Reference](https://docs.theygent.ai/latest/reference/api/): control-plane and inference-plane HTTP APIs
- [Troubleshooting](https://docs.theygent.ai/latest/reference/troubleshooting/): common issues and fixes

## Videos

Each walkthrough has a page with the video, its chapters, and a written summary. All of them are on the YouTube channel: https://www.youtube.com/@TheYgent

- [All video walkthroughs](https://theygent.ai/videos/): the five screen recordings, with chapters and summaries
- [Self-Hosted AI Agent Orchestration: A Full Tour](https://theygent.ai/videos/self-hosted-ai-agent-orchestration/) (23:52): install, create the admin account, install a model with a fit check, benchmark it, then build, trace, and publish an agent with an MCP tool
- [Give Your LLM a Memory: RAG with File Upload and Web Crawl](https://theygent.ai/videos/rag-file-upload-web-crawl/) (9:34): one retrieval source from an uploaded PDF and one from crawling a docs site, embedded locally into pgvector and wired into an agent as tools
- [Voice In, Voice Out: A No-Code AI Agent Pipeline](https://theygent.ai/videos/voice-agent-pipeline/) (5:54): Whisper transcribes, a local model answers, Kokoro speaks the answer — all on local engines
- [Run Local and Remote AI Models in One Agent](https://theygent.ai/videos/local-and-remote-models/) (7:01): a local model triages each request and a router sends hard ones to a hosted API
- [How to Deploy TheYgent to Kubernetes](https://theygent.ai/videos/kubernetes-deployment/) (6:41): build and load the images, apply the manifests, port-forward, and sign in

## Guides

- [Private & offline AI agents](https://theygent.ai/private-ai/): local models only — where data lives, every network touchpoint and when it happens, and running offline or air-gapped
- [Local AI agents on Apple Silicon](https://theygent.ai/apple-silicon/): MLX for chat, vision, and text-to-speech; llama.cpp and whisper.cpp for embeddings and speech-to-text; setting up on a Mac
- [TheYgent's MCP server for Claude Code, Codex & OpenCode](https://theygent.ai/coding-agents/): what a coding agent can hand off — local-model calls that read files itself, running and building agents, indexing and searching docs and code — setup, and what goes where
- [Crawler nodes: web search and scraping for local AI agents](https://theygent.ai/crawlers/): Apify Store actors as agent steps or model tools — browsing with 30-day success rates, choosing the fields a model fills, spend caps, result budgets, measured prompt sizes on a local model, and the MCP-server alternative
- [Reduce Claude Code cost with the AI Gateway](https://theygent.ai/ai-gateway/): what Claude Code costs per session, subagent, and developer; routing subagents and cold-cache turns to a cheaper Claude model; serving a measured share with local models; personal and team gateways, and what leaves them

## Comparisons

Checked against each project's own source and documentation on October 12, 2026, with sources listed on every page.

- [TheYgent vs Dify, n8n, Langflow & Flowise](https://theygent.ai/compare/): visual AI agent builders compared for private, local-model use — who runs the models, telemetry defaults, licenses, MCP, and human-in-the-loop
- [TheYgent vs Dify](https://theygent.ai/compare/dify/): an LLM-app platform that connects to a model server you run, versus a builder with built-in local engines
- [TheYgent vs n8n](https://theygent.ai/compare/n8n/): workflow automation with 400+ integrations, versus AI agents built around local inference; both use the Sustainable Use License
- [TheYgent vs Langflow](https://theygent.ai/compare/langflow/): an MIT-licensed, Python-extensible flow builder with telemetry on by default, versus built-in engines and no telemetry
- [TheYgent vs Flowise](https://theygent.ai/compare/flowise/): an Apache 2.0 agent builder on LangChain.js, versus built-in local engines and crash-resumable runs

## Templates

Thirteen ready-to-run agents ship with TheYgent (install from Settings → Samples). Each page explains the pattern, the models it needs, and its full graph.

- [All agent templates](https://theygent.ai/templates/): the gallery
- [Hybrid reasoner](https://theygent.ai/templates/hybrid-reasoner/): Two models in one run: a local triage model classifies every request and a router sends easy ones to your local model and hard ones (coding, analysis, long-form) to an API model.
- [Private SQL analyst](https://theygent.ai/templates/private-sql-analyst/): A data-privacy pattern: the API model sees ONLY the database schema and your question — never a single row — and writes a SELECT statement; a deterministic guardrail refuses any statement that does not start with SELECT; the query then runs on a local SQLite MCP server and a LOCAL model reads the rows and answers.
- [Expense approver](https://theygent.ai/templates/expense-approver/): Human in the loop with a real approve/reject: a local model assesses the risk of an expense request, the run then WAITS durably for a human decision, and a router either executes the (placeholder) payment step or refuses.
- [Tool belt](https://theygent.ai/templates/tool-belt/): The two ways to use a tool, in one agent: a GraphQL API turned into an MCP server runs as a flow STEP (it always executes), while a REST API turned into an MCP server is WIRED TO the local model as a capability the model decides to call.
- [Second opinion](https://theygent.ai/templates/second-opinion/): Ask a local model AND an API model the same question independently, then a local judge reconciles the two answers into one — flagging any disagreement.
- [PII firewall](https://theygent.ai/templates/pii-firewall/): A privacy router: a deterministic PII guardrail inspects every request BEFORE any model runs.
- [Visual inspector](https://theygent.ai/templates/visual-inspector/): Vision inside a pipeline, not a chat window: a local vision model inspects an image against your acceptance criteria, emits a structured pass/fail verdict, and a router sends the run down the matching branch — the skeleton of a visual QC line.
- [Voice desk](https://theygent.ai/templates/voice-desk/): Voice in, voice out: speech-to-text transcribes the audio, a model answers in spoken prose, text-to-speech reads it back.
- [Art department](https://theygent.ai/templates/art-department/): Local image generation in a pipeline: a local model turns your rough brief into one vivid, concrete image prompt, and a local diffusion model paints it.
- [Handbook Q&A](https://theygent.ai/templates/handbook-qa/): Retrieval as a model capability, fully local: the installer creates a retrieval source in your own Postgres (pgvector), seeds it with a fictional TheYgent company handbook, and wires it to a local model as a search tool the model decides to call — answers cite the handbook section they came from.
- [Web researcher](https://theygent.ai/templates/web-researcher/): A local model with a crawler node wired in as its web-search tool: it searches when a question needs current facts, reads the top three pages as trimmed Markdown, and answers with the URLs it used — the result count and a $0.05 charge cap per search are fixed on the node. Needs an Apify API token.
- [Editorial loop](https://theygent.ai/templates/editorial-loop/): A self-correcting agent: a bounded LOOP re-runs a writer-critic child agent — draft, harsh self-critique, rewrite — until the child approves its own draft or three rounds are up.
- [Batch briefing](https://theygent.ai/templates/batch-briefing/): Durable parallel fan-out with a cost ceiling: a MAP node fans one child agent out per topic (two at a time), collecting a brief for each — a crashed worker resumes only the unfinished branches.

## Blog

- [Letting a Local Model Search the Web Without Letting It Set the Bill](https://theygent.ai/blog/local-models-web-search-crawler-nodes/): crawler nodes measured — every actor field versus the fields a builder exposes (about 13,500 versus 780 prompt tokens on a local model, same accuracy), a model choosing 50 places and a paid add-on, the MLX list-argument crash, result budgets, and how much of the Apify Store converts
- [Give Your Coding Agent Your Local Models: TheYgent as an MCP Server](https://theygent.ai/blog/coding-agents-local-models-mcp/): the MCP server for Claude Code, Codex, and OpenCode — files a local model reads so the coding agent doesn't, building and running agents through tools, indexing a codebase, measured end to end, and what goes where
- [Running Mixture-of-Experts Models Bigger Than Your Mac’s Memory](https://theygent.ai/blog/run-moe-models-bigger-than-memory-on-a-mac/): expert streaming on MLX — a mixture-of-experts model’s experts read from the SSD per token with a GPU cache, identical answers, measured speed and memory, and the limits
- [Building a Local-First Agent Platform Where the Vendor Is Never in the Middle](https://theygent.ai/blog/local-first-agent-platform-architecture/): the architecture — two planes and one seam, logical model IDs, the engine manager, content-addressed agents, durable runs, and checkable privacy

## Source

- [GitHub repository](https://github.com/al2m4n/TheYgent): source code, issues, releases, samples
- [License](https://github.com/al2m4n/TheYgent/blob/main/LICENSE.md): the Sustainable Use License, in full

## Optional

- [Marketing site](https://theygent.ai/): product overview
- [Glossary](https://docs.theygent.ai/latest/reference/glossary/): terms used across the product
- [Environment Variables](https://docs.theygent.ai/latest/reference/environment/): configuration reference
- [Import & Export](https://docs.theygent.ai/latest/import-export/): moving agents and data between installs
- [The Bench](https://docs.theygent.ai/latest/running/bench/): testing and benchmarking models and agents