Your local AI, from setup to Team

What Yggdrasil does

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. Both run local models on computers you already own. You do not need a hosted model account for local inference.

This Core release publishes headless archives and Linux deb and rpm packages. Those files are not the Desktop application, and they are not code-signed. Mobile controllers, an MCP marketplace, and custom orchestrator management are not included.

Install and start your first chat

Yggdrasil Desktop is distributed separately from this Core release. Use the official desktop channels for the packaged app. This page’s release files are Yggdrasil Core. Verify them against SHA256SUMS.txt. Core archives are not code-signed.

On macOS, Homebrew installs Core from this repository. Linux can use a deb or rpm package. Other systems use the headless archive. The daemon serves a web UI at http://127.0.0.1:7331.

1. Open http://127.0.0.1:7331, or open Yggdrasil Desktop if you installed it separately. Follow the hardware and model setup. Allow enough disk space for model files and the managed runtime. The first model and runtime download require internet access.
2. Open Models and install a model suitable for this computer. Wait for installation to finish.
3. Open Chat, choose General Assistant and the installed model, and send a short prompt. The initial response can take longer while the runtime loads the model.
4. Find your app version in the sidebar or Settings and match it to the documentation version above.

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.

Automatic routing can prefer an installed model with tool support for a question needing current information. Choosing This computer keeps the selected model. A model without tool support cannot browse simply because Internet is enabled.

Chat and context

Choose Profile, Run on, and the model in the chat composer. The model choice stays with the conversation. Responses render Markdown, links, lists, and code. Scroll upward to read earlier messages; use Latest to return to the newest response.

The context ring beside Send estimates how much of the running model’s window is used by instructions, tools, conversation, and tool results. Local models use an 8,192-token window, capped lower when the model supports less. This readout is temporary and clears when switching chats.

Tool work appears as a short status, such as Searching the web. Expand Used N tools afterward to see tool names, summaries, and timings. Tool errors appear as short messages; use Diagnostics for investigation.

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 read-only tools stay under Advanced. Save stays disabled until an installed model is available. Leave the read-only tool list empty to use every read-only tool the profile already allows. A selected tool can only narrow that set. Write tools, including the terminal and git add, commit, and push, stay off while the task is unattended. Ask and allow-for-session stay decisions you make in chat, so a scheduled run does not wait for a closed window.

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. 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.

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

Capabilities and permissions

Profiles control which tools a model may use. Enabling a capability permits its tools to run automatically. Existing customized Ask or Deny choices are preserved. In Advanced mode, Allow runs immediately, Ask requests approval in chat, and Deny excludes the tool. A globally disabled tool cannot run.

Internet searches DuckDuckGo and opens public pages. Current answers depend on reachable sources; weather comes from public forecast pages, not a dedicated weather service. Disabling Internet removes web tools from the model prompt.

Files searches, reads, and writes within the workspace. Shell runs local commands. Git can inspect status, diffs, logs, and commits, stage changes, commit, and push. Enable these capabilities only when you intend the assistant to perform those actions.

The Tools screen lists built-in tools and supports inspection and testing. A capability needs a compatible model as well as permission. The simple chat tool loop is limited to 10 calls per turn.

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.

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. Performance → Chat history shows per-role timing and cross-machine activity.

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, then POST /v1/chat/completions. This is an OpenAI-compatible subset, not a promise of support for every hosted API feature.

With LAN access disabled, the default loopback endpoint needs no API key. Enabling local network access requires a key, including for local API requests. Create a named key in API Access and copy its secret when shown; you can rotate or revoke it there. Send it as Authorization: Bearer YOUR_KEY.

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.

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 daemon accepts --data-dir for a custom data location. Stop it with Ctrl+C when running in a terminal. The headless archive does not install a system service.

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

Settings, storage, and privacy

Settings controls appearance, default profile, where chats run, model lifecycle, downloads, notifications, history, and maximum model storage. Advanced mode reveals additional controls. Desktop settings also include keeping the app running in the background and launch at login.

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.

Local inference stays on the selected computer, while Team work sends requests to paired computers. Model downloads and Internet tools make network requests; Git push and shell commands can also access external services. Turning off Internet tools alone does not make all capabilities offline.

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.

Troubleshooting and diagnostics

No reply or model load failure: confirm installation finished, check the selected computer is online, close memory-heavy applications, or try a smaller model. Inspect Models → Running and Diagnostics for runtime failures.

No live web answer: verify Internet is enabled for the profile and the selected model supports tools. A failed search or page fetch can be a network or source issue. Diagnostics → Tool activity shows process-local tool events.

API connection refused: confirm the daemon is running and copy the current endpoint from API Access. A 401 with LAN access enabled means you need a valid API key. Run Test API after changing settings.

Slow chat: inspect Performance for response timing and model speed. Team profiles involve multiple role generations and network work, so compare them separately from a single-model chat.

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.