Your local AI, from setup to Team

What Yggdrasil does

Yggdrasil runs local AI models through a desktop app or a browser connected to its daemon. It manages the llama.cpp runtime, model downloads, chat, tools, and trusted computers on your local network. You do not need a hosted model account for local inference.

Desktop packages target Apple silicon macOS, Windows x64, and Linux x64. Linux headless packages target x64 and ARM64. Mobile controllers, an MCP marketplace, and custom orchestrator management are not included.

Install and start your first chat

Choose the archive for your operating system and processor from this version’s release page. The release includes SHA256SUMS.txt for checking downloaded files. macOS release builds are signed and notarized; Windows builds are unsigned.

On macOS, extract and open Yggdrasil.app. On Windows, extract the whole archive before launching the app. On Linux, keep the app beside yggdrasil-daemon; the desktop requires GTK 3 and WebKitGTK 4.1. Use the headless package for a server without a graphical desktop.

1. Launch Yggdrasil and 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.

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-0.1.0-alpha.28-linux-amd64-headless.tar.gz
cd yggdrasil-0.1.0-alpha.28-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.