Your local AI, from setup to Team

What Yggdrasil does

Yggdrasil runs AI models on computers you already own. Yggdrasil Desktop is the packaged app. Yggdrasil Core is the open-source engine behind it: a daemon, a local web UI, and an HTTP API. You do not need a hosted model account, and your chats, files, and knowledge stay on your computers unless you use a feature that goes online.

Chat answers with sources you can check, remembers what you ask it to, and looks things up on the web when a question needs current information. It reads files you attach and makes documents and spreadsheets you ask for. Knowledge connects your own files, folders, databases, and web APIs, so answers use current prices, stock, and policies without retraining. Automations run prompts on a schedule. Train builds a specialized AI for one job. Computers lets several of your machines share the work.

This Core release publishes headless archives, Linux deb and rpm packages, and a Homebrew formula. They are not the Desktop application, and they are not code-signed. Mobile apps are separate products.

Install and start your first chat

Yggdrasil Desktop is distributed separately from this Core release. The release files are Yggdrasil Core. Verify them against SHA256SUMS.txt. Core archives are not code-signed.

On macOS, Homebrew installs Core: brew tap yeixio/yggdrasil https://github.com/yeixio/yggdrasil-core, then brew install yeixio/yggdrasil/yggdrasil, then run yggdrasil-daemon. On Debian and Ubuntu, add the apt repository shown in the release notes and install the yggdrasil package. RPM packages for x86_64 and aarch64 are attached to each release. The deb and rpm packages install a system service that starts Yggdrasil at boot. Windows and other systems use the headless archive.

The daemon serves the web UI at http://127.0.0.1:7331. Only this computer can reach it until you turn on local network access.

1. Open http://127.0.0.1:7331, or open Yggdrasil Desktop if you installed it. Follow the hardware and model setup. The first model and runtime download need internet access and enough disk space.
2. Open Models and install a model the fit label recommends for this computer. Wait for the download to finish.
3. Open Chat and send a short message. New chats use Auto, which picks an installed model for each message. The first answer can take longer while the model loads.
4. Find your version in the sidebar or Settings, and match it to the documentation version above.

Chat

The composer has the profile, the model, Run on, Effort, and Memory. Model Auto picks an installed model for each message: a quick question stays on a model that is already loaded, coding goes to a coding model, a question about current information or a task on this computer goes to a model that can use tools, and a question about your files or knowledge prefers a larger model. A question about what one of your specialized AIs was trained for goes to that AI. Choose a model yourself to keep it for the chat.

Effort sets how much care an answer gets. Fast answers in one go. Balanced plans requests with several parts and reads a page for each look-up. Thorough reads more, checks figures twice, and uses the largest model that fits. Auto keeps quick questions fast and gives questions about your data, and requests with several parts, more care. Your choice is remembered.

Attach documents, spreadsheets, PDFs, and code files with the paperclip, by dropping them on the message box, or by pasting. The answer cites the file, and later questions in the chat can still use it. Ask for a file, such as a spreadsheet of prices, and the answer comes with a download; spreadsheets are real .xlsx workbooks. Images are not read yet. A scanned PDF has no text to read in chat: connect it in Knowledge instead.

Under each answer, Sources lists the web pages, knowledge passages, files, and memories it used, and What I did lists the model that answered and why, the searches and pages read, and anything that went wrong. A request with several parts, such as comparing three products, shows a checklist while its parts run. Figures are checked against the sources before you see the answer, and a figure that could not be confirmed is called out below it. A notice also appears when a small model answered a question about your data, or when the model that answered is smaller than the one that failed.

Stop ends everything working on the answer, including web look-ups and paired computers, and keeps what was already written. The context ring beside Send shows how much of the model's window the conversation uses. When a long chat passes half the window, older messages are summarized after the reply; they stay saved.

Memory

Say “Remember that…” in any chat, and Yggdrasil keeps it across chats, restarts, and model changes. “Forget…” removes a memory, and “What do you remember?” lists them. Answers that used a memory list it under Sources.

The Memory page lists memories by category. Add a memory, edit or pause one, mark it This computer only, or delete it. A memory marked This computer only keeps any chat that uses it on this computer.

Memory is on by default. Turn it off for one chat with the Memory switch in the composer, or everywhere in Settings. Passwords, keys, and card numbers are never saved. A memory that tries to grant a permission, such as “you can push without asking”, is refused: what tools may do is set only in profiles and Settings.

Connect knowledge

Knowledge keeps catalogs, prices, policies, and documents searchable. When a profile or a specialized AI uses a source, the passages that match each question are added to its answers, and the answer cites them. Changing the data changes the next answer. Nothing is retrained.

Connect knowledge has four kinds of source. File or folder reads files on this computer in place and reindexes them when they change. Upload or paste keeps a copy of what you give it. Database runs one read-only SELECT query on a SQLite file, PostgreSQL, or MySQL; each row becomes a passage, and Yggdrasil never changes the database. Web API fetches a URL that returns JSON, CSV, or text; a list of items becomes one passage per item. Database and Web API sources are fetched again when a question uses data older than the interval you choose, from 5 minutes to a day, and passwords and tokens are stored apart and never shown again.

PDF, Excel, CSV, TSV, JSON, JSONL, Markdown, text, and HTML files work. Each Excel sheet is a table, and each PDF page is cited by its number. Scanned PDFs are read with text recognition; the first one installs the recognizer, about 110 MB, on this computer.

Search matches the words in a question. Install an embedding model, such as Nomic Embed Text v1.5 from Models, and it also matches meaning, so a question about a warranty finds a passage about a guarantee. A source then says when it is searchable by meaning. Try a question shows which passages a question would bring into a chat. Mark a source This computer only to keep chats that use it on this computer. Reindex reads a source again now.

1. Open Knowledge and choose the kind of source in Connect knowledge.
2. Choose the file, folder, or database, paste the content, or enter the URL, then Connect.
3. Use Try a question to check what it finds.
4. Open Profiles in advanced mode and add the source to a profile, or add it to a specialized AI on the Train page.

Choose and manage models

Models separates discovery, installed models, and running models. Choose the target computer before installing or managing models. A downloaded model uses disk space; a running model also needs memory.

In this release, fit labels are Excellent, Good, Tight, May run slowly, and Unsupported. Runtime memory estimates account for the model file, quantization, and configured context. Tight memory is a warning; installation is blocked only for an unsupported machine or backend. Close other applications if free memory is low.

Model details distinguish Estimated speed from Measured performance. A model card is a planning estimate until that model has actually run on your computer. Start with a smaller model if loading fails or responses are too slow.

Browse all models searches Hugging Face for GGUF models, and a model can also be installed from a URL. Embedding and reranker models are supporting models: they help Knowledge search and never answer chats, so the chat menus leave them out. A loaded model is unloaded after 15 minutes without use, unless Settings sets the model lifecycle to manual or another time. Settings also sets the most disk space models may use.

Schedule an automation

An automation is a prompt that the daemon runs on a schedule. Price checks, stock checks, release summaries, and one-time research are the same kind of task: a name, a profile, a schedule, a prompt, and a rule for when to notify you. Open Automations in the sidebar. The list shows whether each task is enabled or paused, the schedule, the latest status and result, and the next run. The daemon keeps that schedule. Closing the web page does not stop it. The desktop app stops the daemon when you quit unless Settings keeps Yggdrasil running in the background.

Create a task by describing it in ordinary language, then choose Set up automation. Yggdrasil fills the name, task, schedule, and notification from that description. These descriptions work: every morning at 8:00 AM with a price below or above an amount; every six hours, and notify only when an item is back in stock; every Friday, with the time defaulting to 8:00 AM when you do not name one; and once tomorrow at 9:00 AM. The task stays in ordinary language. Yggdrasil uses the price, availability, or significance in the result to decide whether to notify you. Adjust any field before you save. The profile, model, time zone, and tools stay under Advanced. Model Auto picks a model for each run. Save stays disabled until an installed model is available. With no tools selected, a run can use the read-only tools the profile allows without asking. Tools you select are approved when you save, including tools that change things, which the form lists apart. A run that reaches a tool you did not approve skips it, finishes, and sends an approval notification naming the tool, instead of waiting for a closed window. Automations use memories and connected knowledge the same way chat does.

Notifications are separate from the run. Every time sends a notice after every success. On change stores the first success as a baseline and notifies only when a later result differs. A condition notifies when the price is below or above the amount you set, when an item becomes available, or when the result is significant. History says why a notice was or was not sent, such as a price that was not below the amount. Only when it fails notifies only when a run fails. Don't notify me stores the result. Notices appear on this computer. Turning off task-finish notifications in Settings turns every automation notice off. Failures are recorded without using those success rules. A timeout or a dropped connection retries the same occurrence up to three times, after one minute and then five minutes. A model that cannot start, an out-of-memory failure, a tool failure, or any other error stays failed. You are notified when those retries are used up or the next occurrence fails too.

Run now starts one occurrence immediately and leaves a paused task paused. If the scheduled time is already due, that occurrence is the one that runs. Otherwise the daemon runs a new occurrence at the current time and still keeps the next scheduled slot, such as tomorrow morning. Pause and Resume turn the task off and on and recompute the next time. Edit changes the stored task. Delete removes the task and its history. History lists each occurrence newest first, with the scheduled time, start, finish, status, result, whether a notice was sent, the model and computer used, and the error when one exists. After a restart, a missed daily or weekly slot runs once for the latest missed time rather than replaying every skipped day. A finished one-time task does not run again.

yggctl talks to the local daemon for the same actions. The address is http://127.0.0.1:7331 unless YGGDRASIL_URL is set. A daemon that is not limited to this computer needs YGGDRASIL_API_KEY.

An automation waits while you chat, and for 20 seconds after, so it does not load a model between your messages. An automation that runs out of memory twice in a row is paused, and its notification says why.

1. Open Automations and choose New automation.
2. Describe when it should run and what it should check. Choose Set up automation and read the task, schedule, and notification. Change the time, day, or threshold if the guess is not the one you want.
3. Choose Test run to try it before it is saved. Create automation stores it.
4. The list shows the next run in the task’s time zone.
5. Use Run now to try it, then open History for the result. Pause stops later scheduled runs until you resume.

yggctl automations create --name "Morning price" --prompt "Check the price" \
  --profile general-assistant --model MODEL_ID --schedule daily --at 08:00 --zone America/Los_Angeles

yggctl automations list
yggctl automations run AUTOMATION_ID
yggctl automations pause AUTOMATION_ID

Train your own AI

Train builds a small assistant that is good at one job. Training teaches your AI how to do its job. Connected knowledge gives it the current information it needs to do that job.

Use examples of good answers, such as chat transcripts or question and answer pairs, to train behavior: the questions it asks, its terminology, its steps, and its tone. Connect data that changes or must stay exact, such as inventory, prices, SKUs, catalogs, and policies, as knowledge. Editing connected knowledge never requires retraining.

Training runs on this computer or a paired one. It needs a Mac with Apple Silicon or a computer with an NVIDIA GPU. The first run downloads the trainer (about 450 MB on a Mac, about 4 GB with NVIDIA's libraries) and the base model's training weights. The base model is not changed, and it stays available on its own.

The plan shows each computer's training fit: the memory training needs, downloads, disk space, and how long it takes. Another computer can train for this one; choose it in the Review step, and the trained AI comes back to this computer. Training waits for chats, automations, and benchmarks to finish before it starts, and a chat during training is still answered, with a note about how long training has left.

A deployed AI can also be exported as one GGUF file from the Deploy step, for LM Studio, Ollama, llama.cpp, and other GGUF tools. The file is a little larger than the base model. Its instructions and connected knowledge stay in Yggdrasil; copy the instructions shown with the file to use as the system prompt elsewhere. A copy of Yggdrasil from the Mac App Store trains on a paired computer unless the app includes the trainer.

1. To see how it works first, choose Try an example. It sets up a sample tire shop assistant with example chats, an inventory, and a policy document, and explains each step. Nothing trains until you press Train.
2. Open Train and choose Build a new AI. Describe the job in a sentence or two.
3. Choose a base model. Yggdrasil recommends one for the job and shows its license, the memory training needs, and how long it takes.
4. Add material. For each file or paste, Yggdrasil recommends Training, Knowledge, or Both and explains why. Review the recommendation before you add it.
5. Review the examples. Fix or exclude flagged examples. At least 10 usable examples are required; about 50 teach a workflow reliably.
6. Review the plan, pick Quick, Balanced, or Highest quality, and start training. You can cancel at any time.
7. Compare base and specialized answers on the test prompts. Evaluation is required before deploying.
8. Deploy. The AI appears in the Chat model menu and in the API as sai:<name>. Retraining creates a new revision; the deployed one keeps answering until you deploy the new one.

Tools, permissions, and connected services

Profiles control which tools a model may use. Turning on a capability allows its tools. In advanced mode, each tool has a permission: Always allow runs it, Ask each time and Ask once per session ask in chat first, and Deny never runs it. Settings sets the defaults for the terminal, file writes, and Git. A tool turned off on the Tools screen cannot run anywhere.

Internet searches DuckDuckGo and reads public pages. Files finds, reads, and writes workspace files. Terminal runs commands. Git inspects a repository, commits, and pushes. Files you can download are made with files.create, which writes only to Yggdrasil's own file store. After an answer reads a web page or a file, a tool that changes something asks first even when the profile allows it, because retrieved content is data, not instructions.

Each message is offered only the tools it needs: web search for current questions, files for a file or folder, the terminal for “run” or “install”, Git for “commit”. A plain question gets no tools. The model cannot call a tool it was not offered. How many tool calls a message may make depends on effort: 3 on Fast, 10 on Balanced, and 16 on Thorough.

Connected services add tools for GitHub and Home Assistant. Connect them in Settings → Connected services with a token; Yggdrasil checks it, stores it apart from the database, and adds it only when a tool runs, so it is never shown to the model. Reading is allowed and changes ask first unless a profile says otherwise.

MCP servers add more tools. On the Tools screen, Add tools offers a gallery of servers, servers already set up in your other apps, pasted configuration, or a custom server. Tool sources lists each server, its tools, its log, and a Sign in action for servers that sign in with a browser. Other AI apps can use Yggdrasil too: API Access → Use Yggdrasil in other AI apps shows what to paste into Claude Desktop, Claude Code, Cursor, VS Code, and other apps.

Notifications

The bell next to the Yggdrasil name shows unread notifications: finished and failed automations, tools an automation skipped, finished or failed model downloads, finished or failed exports, deployed AIs, and newly paired computers. Choose one to go to it. Mark all read clears the count, and Dismiss removes one.

Notifications are kept by the daemon, so ones that arrived while the window was closed are waiting. Finished and failed automations also post a desktop notice, unless Settings turns task-finish notifications off. A repeat from the same source within 10 minutes is folded into the first notification.

Profiles

A profile is an assistant style: its models, tools, connected knowledge, and where it runs. General Assistant answers with one model. Programming (Team) runs a coordinator, a worker, and a reviewer. Research focuses on looking things up. Profiles appear in the sidebar in advanced mode, where you can create, rename, and edit them.

Capabilities turn tool groups on and off, and each tool has its own permission. A profile can list knowledge sources that every chat with it searches, and placement can be Automatic or Prefer this computer.

Orchestration tunes how the profile works: Reasoning level (its effort when a chat leaves effort on Auto), Planning (always or never plan requests with several parts), Workers and Parallelism (how many parts, and side by side or one at a time), Verification (check and report, or check and correct once or twice), Tool calls, Memory (off for this profile), Context budget (how much of the model's window earlier messages may use), Fallback (show the failure instead of answering on another model), and Time limit. Empty fields keep the defaults.

Connect your computers

Computers discovers other Yggdrasil instances on the local network. Pairing establishes trust between computers; it is separate from enabling LAN access to the OpenAI-compatible API.

Run on in the composer, and Run chats on in Settings, choose where chats run: Automatic lets Yggdrasil pick an online paired computer that has the model, and This computer keeps them here. A chat that uses a memory or knowledge source marked This computer only always runs here. Each computer gives chat priority over automations, background knowledge indexing, benchmarks, and training.

1. Run Yggdrasil on both computers on the same LAN. Enable Find other computers in Settings.
2. In Computers, find the other machine and choose Add to team. Approve the incoming request on the other computer; use the displayed pairing code when needed.
3. Confirm both machines appear paired and online. Install the required model on each computer that will run a role.
4. If discovery fails, check network isolation, discovery settings, and firewalls. An offline or revoked computer cannot accept a pinned role.

Run a Team profile

General Assistant uses a simple chat flow. Programming (Team) runs coordinator, worker, and reviewer roles and returns one final answer. Roles can use different models or different paired computers; automatic placement can also keep work on one computer.

1. Install the same model on both paired computers for an easy first run.
2. Select Programming (Team) in Chat and choose an installed model to fill any unset role model choices.
3. For explicit placement, enable Advanced mode and edit the profile roles to pin a model and computer, such as worker on your second machine.
4. Send a short request. The chat timeline identifies the role and computer. In advanced mode, Run details under the answer shows each role's model, computer, and timing.

Connect another app through the API

Open API Access to copy the endpoint and run Test API. The default base URL is http://127.0.0.1:7331/v1. Use GET /v1/models to find a model ID, such as auto or a profile, then POST /v1/chat/completions. The API gets the same assistant as chat: Auto, web look-ups, connected services, answer checks, personalization, and specialized AIs. It is an OpenAI-compatible subset, not every hosted API feature.

With local network access off, the default endpoint on this computer needs no API key. Turning on Local network access requires a key for every request. Create a named key in API Access and copy its secret when it is shown; you can rotate or revoke it there. Send it as Authorization: Bearer YOUR_KEY.

Each key has permissions a request can only narrow: whether it may use memories and connected knowledge (never, on request, or always), which tools (the profile's, read-only, or none), and whether it may choose where it runs. API requests use memories only when they ask, unless the key says always. A request can ask for JSON with response_format, and Yggdrasil checks and repairs the result.

For another computer, use the LAN endpoint shown in API Access rather than localhost. Keep LAN access on a trusted network; the displayed HTTP endpoint does not itself provide public-internet TLS protection.

Apps that speak MCP, such as Claude Desktop, Claude Code, Cursor, and VS Code, can ask your local AI questions, list its models, and search your connected knowledge. API Access → Use Yggdrasil in other AI apps shows what to paste into each.

curl http://127.0.0.1:7331/v1/models

curl http://127.0.0.1:7331/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_LIST","messages":[{"role":"user","content":"Hello"}],"stream":false}'

Run without a desktop

Extract the matching Linux headless archive and run the daemon from the extracted directory. Keep the bundled web directory alongside it. Open http://127.0.0.1:7331 on that computer.

For a remote server, an SSH tunnel lets you reach the loopback UI: ssh -L 7331:127.0.0.1:7331 user@server. Then open http://127.0.0.1:7331 on your own computer, using a different local port if it is already occupied.

The deb and rpm packages run Yggdrasil as the system service yggdrasil.service, as the user yggdrasil, with its data in /var/lib/yggdrasil/.local/share/yggdrasil. Use systemctl status, restart, and stop, and journalctl -u yggdrasil for its log. The headless archive does not install a service: the daemon accepts --data-dir for a custom data location, and Ctrl+C stops it in a terminal.

config.json in the data directory sets ports, addresses, discovery, and static peers, and YGGDRASIL_* environment variables override them for containers. The yggctl command lists, creates, runs, and pauses automations from a terminal, and prints shell completion.

tar -xzf yggdrasil-1.4.0-linux-amd64-headless.tar.gz
cd yggdrasil-1.4.0-linux-amd64-headless
./yggdrasil-daemon

Privacy and what left this computer

Yggdrasil does not send usage telemetry. Chats, memories, knowledge, files, and specialized AIs are stored in the data directory on this computer. Something leaves only when a feature that goes online is used: a web search or page read, a connected service or MCP server, a database or web API you connected, a model or runtime download, a paired computer that answers a chat or trains, or an external server you configured.

Settings → What left this computer lists each of those, newest first: the search queries, page addresses, what was sent to a paired computer or an external server, and what a connected service was asked. It counts them for the last 30 days.

Run records hold the prompts and tool results of past runs, including that list. Keep run records for sets how long they are kept: 7, 30, or 90 days, or Keep them. Delete run records now removes them at once, and clears cached web searches and pages. Chats are not run records; History in Settings decides whether chats are saved.

Memories and knowledge sources marked This computer only keep every chat that uses them on this computer. Text recognition, meaning search, and training on this computer never send your data elsewhere.

Settings and storage

Settings controls appearance, the default profile, where chats run, model lifecycle and storage, downloads, notifications, history, tool permissions, connected services, personalization, and what left this computer. Advanced mode shows Profiles, Tools, and API Access in the sidebar, per-tool permissions, and run details under answers. Desktop settings also keep Yggdrasil running in the background and launch it at login. Saving an automation's schedule turns on Keep running in background, because schedules stop when the daemon stops.

Personalization shapes how answers look in every chat, automation, and API request: length (brief, balanced, or detailed), tone (friendly, neutral, or direct), format (prose or lists), units (metric or imperial), and two short notes, about you and how to answer. It never changes what tools may do.

Default data locations are ~/Library/Application Support/Yggdrasil on macOS, %LOCALAPPDATA%\Yggdrasil on Windows, and ~/.local/share/yggdrasil on Linux. Settings shows the actual data, model, runtime, and log directories. SQLite state, model files, and runtime files live under the data tree.

Before replacing an installation or resetting the app, stop the app and daemon and back up the data directory if you need its state. Review the reset dialog carefully. Install updates from the matching release archive and restart the app.

Diagnostics and performance

Diagnostics shows the health of the control service, the model runtime, the database, networking, storage, and the API, with a plain status for each. What Yggdrasil can do lists every ability, such as looking things up, reading files, or training, with how it works or what would make it possible. Chat answers questions like “Can you generate an image?” from the same list. Tool activity shows recent tool calls. Export diagnostics writes a troubleshooting bundle without secrets.

Performance shows what your AI is doing right now and recent runs with their speed. Compare models runs the same benchmark on several models, and Recent benchmarks keeps the results. In advanced mode, Run details under an answer shows how it was handled: the models and computers used, load time, time to first token, tokens per second, tool calls, and retries.

Troubleshooting

Start with What I did under the answer: it names the model that answered and why, and what went wrong. No reply or a model load failure: confirm the installation finished, check the selected computer is online, close memory-heavy applications, or try a smaller model. A model that cannot load fails at once with the reason.

No live web answer: check that Internet is allowed in the profile, and ask for a search or about something current; a plain question is answered without tools. The same search within 15 minutes is answered from the cache.

An answer did not use your knowledge or memories: use Try a question on the Knowledge page, install an embedding model so search matches meaning, and check that memory is on for the chat. A knowledge source that failed shows the reason; database and web API sources keep answering from the last data fetched.

API connection refused: confirm the daemon is running and copy the current endpoint from API Access. A 401 with local network access on means the request needs a valid API key, and a 403 means the key does not allow what the request asked for. Run Test API after changing settings.

For a bug report, include the app version, OS and processor, model, profile, steps to reproduce, and relevant diagnostics. Remove secrets and private prompt or file content before posting to the public issue tracker.