From 0e03d7d32d5731b9839a1ecca2695f55ecc79cd3 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Tue, 5 May 2026 12:58:57 -0600 Subject: [PATCH] Updated docs again --- Home.md | 7 +- docs/Getting-Started.md | 16 ++-- docs/Installation.md | 28 ++++--- docs/Vault.md | 160 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 183 insertions(+), 28 deletions(-) create mode 100644 docs/Vault.md diff --git a/Home.md b/Home.md index 141647f..a9f273b 100644 --- a/Home.md +++ b/Home.md @@ -1,5 +1,3 @@ -# Home - Welcome to the Loki wiki! A helpful way to use this wiki is to create a RAG from it and then ask questions about Loki, with Loki! Here's an example @@ -19,13 +17,14 @@ in as little time as possible. Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](AICHAT-MIGRATION) to get started. -## Documentation Index +--- + * [AIChat Migration Guide](AICHAT-MIGRATION): Coming from AIChat? Follow the migration guide to get started. * [Installation](docs/Installation.md): Install Loki * [Getting Started](docs/Getting-Started.md): Get started with Loki by doing first-run setup steps, and learn the basics. * [REPL](REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki. * [Custom REPL Prompt](REPL-PROMPT): Customize the REPL prompt to provide useful contextual information. -* [Vault](VAULT): Securely store and manage sensitive information such as API keys and credentials. +* [Vault](docs/VAULT.md): Securely store and manage sensitive information such as API keys and credentials. * [Shell Integrations](SHELL-INTEGRATIONS): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance. * [Function Calling](TOOLS#Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools * [Creating Custom Tools](CUSTOM-TOOLS): You can create your own custom tools to enhance Loki's capabilities. diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md index ba349fe..be79602 100644 --- a/docs/Getting-Started.md +++ b/docs/Getting-Started.md @@ -1,5 +1,3 @@ -# Getting Started - After installation, you can generate the configuration files and directories by simply running: ```sh @@ -13,7 +11,7 @@ guide you through the process when you first attempt to access the vault. So, to loki --list-secrets ``` -### Authentication +# Authentication Each client in your configuration needs authentication (with a few exceptions; e.g. ollama). Most clients use an API key (set via `api_key` in the config or through the [vault](./docs/VAULT.md)). For providers that support OAuth (e.g. Claude Pro/Max subscribers, Google Gemini), you can authenticate with your existing subscription instead: @@ -33,7 +31,7 @@ loki --authenticate my-claude-oauth For full details, see the [authentication documentation](./docs/clients/CLIENTS.md#authentication). -## Configuration +# Configuration The location of the global Loki configuration varies between systems, so you can use the following command to find your `config.yaml` file: @@ -44,7 +42,7 @@ loki --info | grep 'config_file' | awk '{print $2}' The configuration file consists of a number of settings. To see a full example configuration file with every setting defined, refer to the [example configuration file](./config.example.yaml). -### Default LLM +## Default LLM The following settings are available to configure the default LLM that is used when you start Loki, and its hyperparameters: @@ -54,7 +52,7 @@ hyperparameters: | `temperature` | The default `temperature` parameter for all models (0,1); Used unless explicitly overridden | | `top_p` | The default `top_p` hyperparameter value to use for all models, with a range of (0,1) (or (0,2) for some models);
Used unless explicitly overridden | -### CLI Behavior +## CLI Behavior You can use the following settings to modify the behavior of Loki: | Setting | Default Value | Description | @@ -66,7 +64,7 @@ You can use the following settings to modify the behavior of Loki: | `wrap` | `no` | Controls whether text is wrapped (can be `no`, `auto`, or some `` | | `wrap_code` | `false` | Enables or disables the wrapping of code blocks | -### Preludes +## Preludes Preludes let you define the default behavior for the different operating modes of Loki. The available settings are shown below: @@ -76,7 +74,7 @@ shown below: | `cmd_prelude` | This setting lets you specify a default `session` or `role` to use when running one-off queries in Loki via the CLI.
Values can be | | `agent_session` | This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. `temp`, `default`) | -### Appearance +## Appearance The appearance of Loki can be modified using the following settings: | Setting | Default Value | Description | @@ -84,7 +82,7 @@ The appearance of Loki can be modified using the following settings: | `highlight` | `true` | This setting enables or disables syntax highlighting | | `light_theme` | `false` | This setting toggles light mode in Loki | -### Miscellaneous Settings +## Miscellaneous Settings | Setting | Default Value | Description | |----------------------|---------------|------------------------------------------------------------------------------------------------------------------| | `user_agent` | `null` | The name of the `User-Agent` that should be passed in the `User-Agent` header on all requests to model providers | diff --git a/docs/Installation.md b/docs/Installation.md index 842cd11..7edf3a2 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,6 +1,4 @@ -# Installation - -## Prerequisites +# Prerequisites Loki requires the following tools to be installed on your system: * [jq](https://github.com/jqlang/jq) * `brew install jq` @@ -13,9 +11,9 @@ Loki requires the following tools to be installed on your system: These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation, and they are used within agents and tools. -## Install +# Install -### Cargo +## Cargo If you have Cargo installed, then you can install `loki` from Crates.io: ```shell @@ -25,7 +23,7 @@ cargo install loki-ai # Binary name is `loki` cargo install --locked loki-ai ``` -### Homebrew (Mac/Linux) +## Homebrew (Mac/Linux) To install Loki from Homebrew, install the `loki` tap. Then you'll be able to install `loki`: ```shell @@ -42,8 +40,8 @@ To upgrade `loki` using Homebrew: brew upgrade loki ``` -### Scripts -#### Linux/MacOS (`bash`) +## Scripts +### Linux/MacOS (`bash`) You can use the following command to run a bash script that downloads and installs the latest version of `loki` for your OS (Linux/MacOS) and architecture (x86_64/arm64): @@ -51,7 +49,7 @@ OS (Linux/MacOS) and architecture (x86_64/arm64): curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/loki/main/install_loki.sh | bash ``` -#### Windows/Linux/MacOS (`PowerShell`) +### Windows/Linux/MacOS (`PowerShell`) You can use the following command to run a PowerShell script that downloads and installs the latest version of `loki` for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64): @@ -59,7 +57,7 @@ for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64): powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/loki/main/scripts/install_loki.ps1 | iex" ``` -### Manual +## Manual Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/releases) page for the following platforms: | Platform | Architecture(s) | @@ -68,14 +66,14 @@ Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/re | Linux GNU/MUSL | x86_64, aarch64 | | Windows | x86_64, aarch64 | -#### Windows Instructions +### Windows Instructions To use a binary from the releases page on Windows, do the following: 1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS. 2. Use 7-Zip or TarTool to unpack the Tar file. 3. Run the executable `loki.exe`! -#### Linux/MacOS Instructions +### Linux/MacOS Instructions To use a binary from the releases page on Linux/MacOS, do the following: 1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS. @@ -84,7 +82,7 @@ To use a binary from the releases page on Linux/MacOS, do the following: 4. Now you can run `loki`! -## Tab-Completions +# Tab-Completions You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile: ```shell # Bash @@ -109,9 +107,9 @@ $env:COMPLETE = "powershell" loki | Out-String | Invoke-Expression ``` -## Shell Integration +# Shell Integration You can integrate Loki's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the -corresponding [shell integration script](./scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to +corresponding [shell integration script](https://github.com/Dark-Alex-17/loki/tree/main/scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to shell commands by pressing `Alt-e`. For example: ```shell diff --git a/docs/Vault.md b/docs/Vault.md new file mode 100644 index 0000000..07bc0a3 --- /dev/null +++ b/docs/Vault.md @@ -0,0 +1,160 @@ +The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets +anywhere in your configurations. + +It's based on the [G-Man library](https://github.com/Dark-Alex-17/gman) (which also comes in a binary format) which +functions as a universal secret management tool. + +![Vault Demo](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-demo.gif) + +# Quick Links + +- [Usage](#usage) + - [CLI Usage](#cli-usage) + - [REPL Usage](#repl-usage) +- [Motivation](#motivation) +- [How it works](#how-it-works) +- [Supported Files](#supported-files) +- [Environment Variable Secret Injection in Agents](#environment-variable-secret-injection-in-agents) + + +--- + +# Usage +The Loki vault can be used in one of two ways: via the CLI or via the REPL for interactive usage. + +## CLI Usage +The vault is utilized from the CLI with the following flags: + +```bash +--add-secret Add a secret to the Loki vault +--get-secret Decrypt a secret from the Loki vault and print the plaintext +--update-secret Update an existing secret in the Loki vault +--delete-secret Delete a secret from the Loki vault +--list-secrets List all secrets stored in the Loki vault +``` +(The above is also documented in `loki --help`) + +Loki will guide you through manipulating your secrets to make usage easier. + +## REPL Usage +The vault can be access from within the Loki REPL using the `.vault` commands: + +![Loki Vault REPL](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-repl.png) +![Loki Vault REPL Commands](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-repl-commands.png) + +The manipulation of your vault is guided in the same way as the CLI usage, ensuring ease of use. + +# Motivation +Loki is intended to be highly configurable and adaptable to many different use cases. This means that users of Loki +should be able to share configurations for agents, tools, roles, etc. with other users or even entire teams. + +My objective is to encourage this, and to make it so that users can easily version their configurations using version +control. Good VCS hygiene dictates that one *never* commits secrets or sensitive information to a repository. + +Since a number of files and configurations in Loki may contain sensitive information, the vault exists to solve this problem. + +Users can either share the vault password with a team, making it so a single configuration can be pulled from VCS and used +by said team. Alternatively, each user can maintain their own vault password and expect other users to replace secret values +with their user-specific secrets. + +# How it works +When you first start Loki, if you don't already have a vault password file, it will prompt you to create one. This file +houses the password that is used to encrypt and decrypt secrets within Loki. This file exists so that you are not prompted +for a password every time Loki attempts to decrypt a secret. + +When you encrypt a secret, it uses the local provider for `gman` to securely store those secrets in the Loki vault file. +This file is typically located at your Loki configuration directory under `vault.yml`. If you open this file, you'll see a +bunch of gibberish. This is because all secrets are encrypted using the password you provided, meaning only you can decrypt them. + +Secrets are specified in Loki configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/): + +``` +{{some_variable}} +``` + +So whenever you want Loki to use a secret from the vault, you simply specify the secret name in this format in the applicable +file. + +**Example:** +Suppose my vault has a secret called `GITHUB_TOKEN` in it, and I want to use that in the MCP configuration. Then, I simply replace +the expected value in my `mcp.json` with the templated secret: + +```json +{ + "mcpServers": { + "atlassian": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"] + }, + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "{{GITHUB_TOKEN}}" + } + } + } +} +``` + +At runtime, Loki will detect the templated secret and replace it with the decrypted value from the vault before executing. + +# Supported Files +At the time of writing, the following files support Loki secret injection: + +| File Type | Description | Limitations | +|-------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `config.yaml` | The main Loki configuration file | Cannot use secret injection on the `vault_password_file` field | +| `functions/mcp.json` | The MCP server configuration file | | +| `/tools.` | Tool files for agents | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents)) | + + +Note that all paths are relative to the Loki configuration directory. The directory varies by system, so you can find yours by +running + +```shell +loki --info | grep config_dir | awk '{print $2}' +``` + +# Environment Variable Secret Injection in Agents +Secrets from the Loki vault can be injected into agent `tools.sh/tools.py` as environment variables. This is done as +follows: + +1. Ensure a secret named `MY_USERNAME` is in your Loki vault. +2. Set the name of the secret as the default value for a variable + `/config.yaml` + ```yaml + name: Username + description: An AI agent that demonstrates agent capabilities + instructions: | + You are a AI agent designed to demonstrate agent capabilities. + variables: + - name: username + description: Your user name + # Configure the secret you want to inject using the same templating mentioned above; i.e. wrap the + # case-sensitive name in '{{}}' + default: '{{MY_USERNAME}}' + ``` +3. Reference the variable in your `/tools.` file using the familiar variable injection name; that is, + since the name of the variable is `username`, the environment variable that will be provided to the tool call will + be named `LLM_AGENT_VAR_USERNAME` + `tools.sh` + ```bash + #!/usr/bin/env bash + # @env LLM_OUTPUT=/dev/stdout The output path + + # @cmd Get my username + get_my_username() { + echo "$LLM_AGENT_VAR_USERNAME" >> "$LLM_OUTPUT" + } + ``` + +For more information about variable usage within agents, refer to the [Variables section](./AGENTS.md#user-defined-variables) of the [Agents README](./AGENTS.md) +