Repository navigation
Releases
v2.0.0: TheYgent is now Ertir
TheYgent is now Ertir. Ertir (formerly TheYgent) 2.0.0 is the first release under the new name. It is the same project: the same code, the same maintainer and the same license (Sustainable Use License). Your installation and your data carry over unchanged.
The new name
- Ertir replaces TheYgent in the app, the docs and the website.
- Website: ertir.dev. Docs: docs.ertir.dev. Links to
theygent.aianddocs.theygent.airedirect to the matching page. - Repository: github.com/al2m4n/ertir. GitHub redirects the old
al2m4n/TheYgentURLs, so clones, issues and pull requests keep working.
What stays the same
Technical names keep the old spelling, so scripts and configuration keep working:
- environment variables:
THEYGENT_* - the data folder:
~/.theygent - headers:
X-TheYgent-Signature(webhooks) andX-TheYgent-Gateway-Key(AI gateway) - Python, npm, Docker and Kubernetes names:
theygent…
The name change in the docs lists what changed and what didn't.
Where the new name shows up
- App: the sidebar, the welcome screen and page titles say Ertir.
- API titles and messages: the services' OpenAPI titles, and the AI gateway's error messages and reports, say "Ertir AI gateway". Anything that matched the old "TheYgent AI gateway:" message prefix needs updating.
- MCP sign-in: when Ertir signs in to an MCP server with OAuth, the consent screen shows "Ertir". Existing connections are unaffected.
- Samples: the Handbook Q&A sample's fictional company is now called Ertir, and the Visual Inspector sample checks the new social card at
ertir.dev. Newly installed copies use the new name. Agents you already installed are unchanged.
Also in this release
- Docs: the early versions' canonical URLs point at
/latest/, so search engines index the current docs (#103).
Upgrading
- No database migrations.
- No changes to API routes, request or response fields, or existing agents and their content hashes.
Thank you to everyone who used, starred and reported issues on TheYgent. Ertir is the same project under a new name.
Full changelog: v1.3.3...v2.0.0
v1.3.3
TheYgent 1.3.3 is a patch release with two RAG fixes. Neither one limited how big a single document can be. That limit is the rag.max_upload_bytes setting: 50 MiB by default, up to 1 GiB, under Settings → RAG.
RAG: the document list no longer stops at 500 (#96)
A source's document list showed only its first 500 documents and dropped the rest without saying so. Ingest and search always used every document; only the list was cut short.
- RAG page: click a source's name to see its documents, oldest first. A large source loads 100 at a time and shows "Showing X of N documents" with a Load more button.
- API:
GET /rag/sources/{id}/documentstakeslimit(1–500, default 500) andafter, and returnsnext_after. Pass that value asafterto get the next page;nullmeans you have them all. Anafterthat names no document of the source returns400 invalid_rag_cursor. A call without these parameters gets the same first page as before, plusnext_after.
MCP server: add_rag_files follows your upload limit (#96)
add_rag_files refused any file over 50 MiB, even after an admin had raised the limit. It now streams each file from disk, so a large file isn't held in the MCP server's memory, and lets the control plane enforce the limit. A file over the limit is skipped, and its result names the limit and where to raise it. The rest of the batch continues.
One call still indexes at most 500 files, and says so in its result.
Upgrading
- No database migrations.
- No changes to existing agents or their content hashes.
- One additive API change: the paging parameters and the
next_afterfield above. Existing callers keep working.
Full changelog: v1.3.2...v1.3.3
v1.3.2
TheYgent 1.3.2 is a security patch. It updates one dependency and changes no behavior.
aiohttp 3.14.3 → 3.14.5 (#95)
Fixes three advisories:
- High: GHSA-2g87-pp6c-29x5, excessive or unbounded memory and CPU use.
- High: GHSA-5wr8-gcqf-gqf3, no initial request or header timeout on the server side.
- Low: GHSA-494j-54xm-rwp3, the Secure attribute not enforced for a shared cookie.
aiohttp is used only as the HTTP client of the inference plane's dispatch layer (litellm). TheYgent runs no aiohttp server. Every fixed release needs a newer yarl, so yarl moves from 1.24.2 to 1.25.1.
Known open alert
- braces (GHSA-vfj7-8cjw-p6xm) has no patched release. It comes in only through the shadcn CLI's file matching (fast-glob → micromatch), which is never part of the built interface.
Upgrading
- No database migrations.
- No changes to existing agents or their content hashes.
- No API, setting or configuration changes.
Full changelog: v1.3.1...v1.3.2
v1.3.1
TheYgent 1.3.1 is a patch release. It finishes the cut-off stream fix from 1.2.1 for remote models.
A remote model's reply cut off mid-stream can be reported (#91)
1.2.1 started checking local engines for streams that stop partway. Remote (openai-compatible) models were still passed through unchecked. When a remote server stopped mid-reply, the dispatch layer closed the stream as though it had finished, and your agent got a shorter answer with nothing to say it was cut off.
- The opt-in. Click a remote chat model in Registries and tick Report a reply cut off mid-stream. Over the management API, it's
"requireFinishReason": trueon the registration. - With it on:
- A streamed reply that stops before the server's own finish reason ends with an
engine_dropped_requesterror frame. - What arrived before the cut is still relayed.
- Streams that end normally are unchanged.
- A streamed reply that stops before the server's own finish reason ends with an
- Why it's off by default. The check relies on the server ending every streamed reply with a finish reason. One that never does would have every reply fail right after the full answer. Anthropic's OpenAI-compatible API was checked and sends one on plain replies, tool calls and replies stopped by a token limit. No other hosted server was checked yet, so the check is opt-in per model.
- Not changed. A request the server drops before it starts replying is named either way, as in 1.2.1. Local engines are always checked.
- The error message. For a remote model,
engine_dropped_requestnow points at the server's own log or the provider's status page.
See A reply cut off mid-stream can read as finished and Troubleshooting.
Also in this release
- Website. The home page now features MoE expert streaming on MLX (#92).
- Contributor docs. Every module has an
AGENTS.mdcontext map, and CI checks that the maps stay in step with the tree (#93).
Upgrading
- No database migrations.
- No changes to existing agents or their content hashes. The new field is on the inference plane's registration only, never on the graph.
- New registration field:
requireFinishReasonon reachable (openai-compatible) bindings, defaultfalse. It is rejected on managed bindings. - Rolling back the inference plane. After 1.3.1 runs,
registry.jsonstoresrequireFinishReasonfor every remote model. An inference plane from 1.3.0 or earlier doesn't know the field and skips those models on load, so re-register them if you roll back.
Full changelog: v1.3.0...v1.3.1
v1.3.0
TheYgent 1.3 adds crawler nodes. Browse thousands of hosted scrapers and crawlers (Apify Actors), add one to an agent, and run it as a step, or wire it to an llm so the model can search the web, read a site, or find places. You decide what each call may do, not the model.
Crawler nodes (#90)
- A Crawlers browser.
- It searches the Apify Store through your control plane. Your browser never calls Apify.
- Each card shows the Actor's pricing, users, and 30-day run success rate, so an Actor that usually times out shows as such before you install it.
- Pick the fields the model may fill and press Add crawler. The node lands on the canvas, already wired into the llm's tools when you add it from one.
- The builder decides what a call does.
- The model fills only the fields you expose, usually one or two.
- Result counts, paid add-ons and proxies stay fixed on the node, and arguments the model invents are dropped.
- Offered every field, a local model in testing asked for 50 places per search and turned on paid review scraping. A crawler node keeps those fixed.
- Small prompts for local models. Three Actors offered as crawler nodes cost about 780 prompt tokens on Qwen3.6-35B, against about 13,500 when every field is offered. List fields default to one value per call, the shape local models fill reliably.
- Spend and size caps.
- Each node has a per-run spend cap (
maxChargeUsd), held under a platform ceiling:crawler.max_charge_usdon Settings → Crawlers, default $1.00. - Results are trimmed to the fields you choose, within a character budget.
- Each node has a per-run spend cap (
- Steps or tools, in both runtimes.
- Interactive runs make one synchronous call, capped at 300 seconds.
- Durable runs start the Actor, poll it, and read its dataset as separate steps, so a long crawl survives a restart. A resumed run polls the run it already started instead of paying for a second.
- Cost in the trace. Crawler spans record the Actor, the item count, the cap and, on durable runs, what the run cost (
crawler.usage_total_usd). - Your token stays a secret. The Apify token is stored once as an encrypted connection and resolved at call time. It never appears in the agent, a trace, or the durable journal.
- A new sample: Web researcher. A local model with a
web_searchcrawler, capped at three results and $0.05 a run. Install it from Settings → Samples and set your token.
Start with the Crawler node docs, or read the overview and the blog post. Prefer giving a capable model every Actor field? Apify through the MCP hub works too, with no crawler node.
Also in this release
- Website.
- A crawlers page and the blog post.
- The Web researcher template, bringing the templates to 13.
- The home page announcement.
- Docs.
- The crawler node and the MCP-hub alternative.
- The privacy page, which notes that a crawler node sends its input to the provider it names.
- The API and environment references.
- The observability page's crawler span attributes.
Upgrading
- No database migrations.
- No changes to existing agents or their content hashes.
- New IR node type:
crawler, withCrawlerConfigandCrawlerLimits. - New endpoints:
GET /crawlers/catalog,GET /crawlers/catalog/actorandPOST /crawlers/catalog/convert. - New error codes:
invalid_actor,crawler_provider_unknown,crawler_not_found,crawler_schema_unavailableandcrawler_catalog_error. - New setting:
crawler.max_charge_usd, with the environment capTHEYGENT_CRAWLER_MAX_CHARGE_USD. - Samples: a sample connection may now be
http_auth.
Known limits
- Apify only, for now. The provider is a closed list so each new provider is a deliberate addition. Apify is a hosted service and needs an Apify account; its free plan includes $5 of usage a month.
- Not run against real Apify. Runs were tested against a local stand-in for Apify's run API, because no Apify token was available. Browsing was checked against the real Store.
- No cost figure on interactive runs. Apify's synchronous endpoint names no run, so only durable runs record what a call cost.
Full changelog: v1.2.1...v1.3.0
v1.2.1
TheYgent 1.2.1 is a patch release with two fixes that apply to every tool, not only to the new ones.
Tool results are capped (#89)
An llm's tool loop used to send each tool result back to the model whole. One web tool returning three pages produced a 50,000-character message, more than a local model's context holds.
- The cap. Every tool result is now cut at a limit:
- It applies to builtin, REST, MCP and retrieval tools, in both interactive and durable runs.
- A marker ends the cut result, saying how many characters were left out.
- The model still answers from the part it saw.
- The default. The limit comes from a new platform setting,
tools.result_max_chars, on a new Settings → Tools tab.- The default is 16,000 characters (about 4,000 tokens).
- The allowed range is 1,000 to 1,000,000.
- A change applies from the next run.
- Per node. An llm node can set its own max tool result characters in its Tools panel. In the IR it's the optional
maxToolResultChars; graphs without it keep their content hashes. - What the trace records. The run inspector still records each whole result. Each tool span adds
tool.result_charsandtool.result_truncated.
A dropped engine request is named, not blank (#89)
mlx-lm's Qwen3 tool parser fails when a model writes plain text where a list or object argument is expected. The failure escapes the engine's handler, and the engine closes the connection without a response.
- Before:
- Non-streaming requests ran the same generation three times, through retries, and then failed with an opaque connection error.
- Streaming requests ended as a blank, apparently successful answer.
- Now:
- The inference plane answers
502 engine_dropped_requestafter one attempt, naming the engine log. - On MLX with tools offered, the message also names the likely parser cause.
- A streaming request ends with an error frame carrying the same code.
- The inference plane answers
- The engine keeps serving. Later requests to the same engine are unaffected.
- No retries to managed engines. The inference plane no longer retries a request to a managed engine, because a failure there repeats.
Docs
- Settings reference. A new Platform settings page covers every setting by tab.
- LLM node. The LLM node page covers the result cap.
- The new error.
engine_dropped_requestis covered in Troubleshooting and on the Engines page.
Upgrading
- No database migrations.
- No changes to existing agents or their content hashes; the new IR field is optional.
- New error code:
engine_dropped_request, on the inference plane's/v1/chat/completions. - New setting:
tools.result_max_chars.
Full changelog: v1.2.0...v1.2.1
v1.2.0
TheYgent 1.2 brings an MCP server for coding agents. Add it to Claude Code, Codex, OpenCode or any MCP client, and the coding agent gets TheYgent as tools. It can offload work to your local models, run and build agents, and search your docs and code.
The MCP server (#87)
-
Offload to a local model.
ask_modelsends a prompt to a model on your inference plane and returns its answer.filesattaches local files. The MCP server reads them itself and sends them only to the model, so a long log never enters the coding agent's context; only the answer comes back.think: falseturns a reasoning model's thinking off. On a commit-title prompt that meant 16 generated tokens instead of 417.
-
Run your agents.
list_agents,run_agentandget_runrun any published agent by id or name, on your own models and tools. Every run is traced on the Runs page. -
Build agents.
agent_authoring_guideis generated from the runtime's own node registry.validate_agentapplies the publishing rules locally, andrun_graphtest-runs a document without saving it.create_agentandpublish_agent_versionpublish it.list_samplesandinstall_samplesinstall the sample agents.
What the coding agent builds is an ordinary agent that opens in the editor.
-
Search your docs and code.
create_rag_sourcecreates a retrieval source.add_rag_filestakes files, folders, or globs such asdocs/**/*.md. It skips hidden, dependency and build directories, and names each document by its path in the project.search_raguses the same hybrid retrieval as agents.
In a live run, 21 files were indexed and searchable in about nine seconds.
-
Your machine, your key. The server runs beside the coding tool, over stdio or streamable HTTP, and holds no state. Model calls go straight to the inference plane. Everything else goes to the control plane with a personal API key (
THEYGENT_API_KEY), which acts with your role. -
Setup in one command.
make mcp-setupprints the configuration for Claude Code, Codex and OpenCode, with your checkout's path filled in.
Start with Use TheYgent from coding agents and Tools & recipes, or read the overview and the blog post.
Also in this release
- Retrieval indexes source code (#87). Uploads accept source code and config files: Python, TypeScript/JavaScript, Go, Rust, Java, Swift, C/C++, shell, SQL, YAML, TOML and more. They index as plain text, from the RAG page and from
add_rag_files. - MLX prompt-cache size (#86). A new MLX launch setting,
promptCacheSize, sets how many prompt states the engine keeps for reuse. The default is 10. Raise it when one model serves several agents or concurrent runs. The LLM node docs now explain why a fixedseedcosts prompt reuse on MLX's hybrid models. - New environment variables for the MCP server:
THEYGENT_API_KEY,THEYGENT_MCP_DEFAULT_MODELandTHEYGENT_MCP_RUN_TIMEOUT_S. It also readsTHEYGENT_CONTROL_PLANE_URLandTHEYGENT_INFERENCE_PLANE_URL. - Website. A new coding-agents page, a blog post, and the home page announcement.
Upgrading
No database migrations and no changes to agents or the IR. Nothing to install: the coding tool starts the MCP server with uv run, which syncs the new theygent-mcp package on first use. Follow the setup guide.
Known limits
- No durable runs from the MCP tools.
run_agentandrun_graphstart ordinary runs. Agents with durable-only nodes (human approval, subgraph, loop, map) still run from the interface or the API. - Timeouts. Long agent runs need the coding tool's tool timeout raised. Codex stops a tool call after 60 seconds by default; the setup guide shows where to raise it for each tool.
- Verified clients. Claude Code was verified end to end, with tools called by the model. OpenCode's printed configuration connects (
opencode mcp list). Codex was checked against its documented configuration only.
Full changelog: v1.1.0...v1.2.0
v1.1.0
TheYgent 1.1 runs mixture-of-experts models bigger than your Mac's memory. On the MLX engine, a mixture-of-experts (MoE) chat model can keep its experts on the SSD. Each layer reads only the experts its router picks, and recently used experts stay in a memory cache. The answers are identical to the fully loaded model's; it's slower.
Expert streaming on MLX (#85)
-
Same answers, far less memory. The model's shared part stays loaded, and the routed experts are read from the model's own files as each token needs them. Measured with Qwen3.6-35B-A3B in 4-bit (20 GB) on a 36 GB Apple Silicon Mac:
How it runs Memory Speed Fully loaded 19.7 GB 53 tokens/s Streaming, every expert cached 20 GB 34 tokens/s Streaming, 4 GB cache, cold SSD 5.7 GB 9 tokens/s Streaming, smallest cache, cold SSD 1.8 GB 4 tokens/s -
Off by default, per model. A model that fits in memory is always faster fully loaded. To turn streaming on:
- in the catalog's install dialog;
- in a model's settings on the Registries page;
- through the API, with the registration params
streamExpertsandexpertCacheGb.
-
Cache size. Expert cache (GB) defaults to half your memory, less the model's shared part.
-
Find MoE models in the catalog. The Hugging Face catalog marks mixture-of-experts models MoE, and a new MoE filter shows only those. Installing the MLX variant of one that won't fit offers Stream experts from disk, already ticked.
-
Loud refusals. A model the feature can't stream is refused when its engine starts, with the reason in the engine log. That covers a model without experts, one whose experts are a kind it doesn't read, and a checkpoint that wasn't converted for MLX.
Start with MoE models bigger than memory in the docs, or read how it works, with the numbers.
Also in this release
- Catalog installs can carry registration params. They're checked before the download starts.
- Edit registration. Models registered from a Hugging Face id get an Edit registration button to reach their settings.
- New environment variable
THEYGENT_MLX_PYTHON. It points expert streaming at the Python that mlx-lm is installed in. That Python is normally found frommlx_lm.serveron its own. - Website.
Upgrading
No database migrations and no changes to agents or the IR. Expert streaming needs mlx-lm (make engines installs it on a Mac); it was verified with mlx-lm 0.31.3.
Known limits
- Apple Silicon, MLX, chat only. Expert streaming is for mixture-of-experts chat models in MLX format, on Apple Silicon. llama.cpp and vLLM are not covered.
- Verified architectures. Verified on Qwen3-MoE and Qwen3.6-MoE. Other architectures built on mlx-lm's standard expert block should work but are unverified.
- Long prompts. The first reply to a long prompt is slow from a cold disk, because processing it touches nearly every expert.
- Parallel requests make the cache less effective.
Full changelog: v1.0.2...v1.1.0
v1.0.2
TheYgent 1.0.2 fixes how search engines see the documentation and gives every walkthrough video its own page. Nothing changes in the product, the database schema, or the IR.
Documentation (docs.theygent.ai)
- Canonical links that resolve. Every docs page told search engines its canonical address was
/latest/<version>/…, a path that never existed, and the docs sitemap listed only those addresses. Each page now names its real/latest/URL, and the addresses the earlier versions published redirect (301) to the pages they meant. (#82) - The domain root serves the Bing Webmaster Tools verification file.
Website (theygent.ai)
- Video walkthroughs (#82): each of the five screen recordings has a page with the player, a written summary, chapters (marked up so search results can link straight to a moment), and links into the docs. These are the full tour, RAG with file upload and web crawl, a voice agent, local and hosted models in one agent, and a Kubernetes deployment.
- The home page links to the walkthrough pages, and the site's structured data names the YouTube channel.
Upgrading
Nothing to do: no code, migration, or configuration changes.
Full changelog: v1.0.1...v1.0.2
v1.0.1
TheYgent 1.0.1 is a website and documentation release. Nothing changes in the product, the database schema, or the IR.
Website (theygent.ai)
- The AI Gateway on the landing page (#80): what it observes, how it routes, and where it runs.
- Private & offline AI (#81): where each kind of data lives, every network connection TheYgent makes and when, and how to run offline or air-gapped.
- Local AI on Apple Silicon (#81): MLX for chat, vision, and text-to-speech; llama.cpp and whisper.cpp for embeddings and speech-to-text.
- How it compares (#81): TheYgent next to Dify, n8n, Langflow, and Flowise. Every claim is dated and cites each project's own source or docs, and each page says where the other product is the better pick.
- Home page:
- Privacy and Compare in the top nav, a Go Deeper row, and five new FAQ entries.
- Corrections: the quickstart now includes the
.envstep, and the MLX note no longer claims the Neural Engine.
Documentation (docs.theygent.ai)
- Privacy and data flow: the checkable version of the privacy promise, including the one automatic request (LiteLLM's public price list at inference-plane startup, which carries no user data and falls back offline).
- llms-full.txt: the whole documentation as one Markdown file, for answer engines and coding agents.
- Corrected an outdated warning that said the control plane performs no authentication. It requires sign-in; the inference plane is the part to keep off untrusted networks.
Upgrading
Nothing to do: no code, migration, or configuration changes.
Full changelog: v1.0.0...v1.0.1