Many popular models on Hugging Face — including Llama 3, Gemma, Mistral, and other instruction-tuned families — are published under a gated licence that requires you to accept terms of use on the Hub and authenticate with a personal read token before downloading. Odysseus Portable has a built-in token resolution pipeline that checks several locations automatically, so once you store your token in any one of the supported places it is picked up without further configuration. The Cookbook download UI also exposes a token field directly in the browser, meaning you never have to touch the terminal at all if you prefer a graphical workflow.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/techjarves/Odysseus-Portable/llms.txt
Use this file to discover all available pages before exploring further.
A Hugging Face token is only required for gated or private model repositories. All public GGUF models available without a login — including the vast majority of community quantisations hosted on Hugging Face — download without any credentials.
Setting Up Your Token
Create a Hugging Face Read token
Go to https://huggingface.co/settings/tokens and sign in. Click New token, choose the Read role, give it a name (e.g.,
odysseus-portable), and click Generate a token. Copy the token — it starts with hf_.Pass the token as an environment variable at launch
Set either
HF_TOKEN or HUGGING_FACE_HUB_TOKEN in your shell before starting Odysseus Portable. Both names are recognised and checked in that order.- Linux / macOS
- Windows (Command Prompt)
- Windows (PowerShell)
Alternative: Use the Cookbook UI Token Field
If you prefer not to set any environment variables, you can enter your token directly in the browser without restarting:Open the Cookbook tab
Navigate to
http://127.0.0.1:7070 and click the Cookbook tab in the Odysseus interface.Open Environment settings
Click the Environment or settings icon within the Cookbook panel to expand the environment configuration section.
Alternative: huggingface-cli Login
If you have already authenticated with the official Hugging Face CLI on the host machine, Odysseus Portable picks up the stored token automatically — no additional configuration is needed:~/.cache/huggingface/token (current) or ~/.huggingface/token (legacy), both of which are checked by Odysseus Portable’s token resolution pipeline.
Token Resolution Order
When a Cookbook download requires authentication, Odysseus Portable resolves the token by checking sources in the following order, stopping as soon as a non-empty value is found:Cookbook UI state (highest priority)
A token entered directly into the HF Token field inside the Odysseus Cookbook web interface. This is stored in
odysseus/data/cookbook_state.json in an encrypted form and takes precedence over all other sources.HF_TOKEN environment variable
The
HF_TOKEN environment variable set in the shell or passed at launch.HUGGING_FACE_HUB_TOKEN environment variable
The
HUGGING_FACE_HUB_TOKEN environment variable, also recognised by many Hugging Face tools.~/.cache/huggingface/token
The token file written by the official
huggingface-cli login command on the host system (~/.cache/huggingface/token).Why does Odysseus need to patch the token loader?
Why does Odysseus need to patch the token loader?
The upstream Odysseus application only reads the HF token from its own internal state file by default. Odysseus Portable applies a self-healing patch to
cookbook_routes.py at each startup that extends this lookup to also check the HF_TOKEN and HUGGING_FACE_HUB_TOKEN environment variables and both standard token file paths used by the huggingface-cli toolchain. This means credentials you have already configured system-wide are honoured without any extra steps.