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 - `role:` to define a role
- `session:` to define a session
- `:` to define both a session and a role to use
|
| `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.
+
+
+
+# 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:
+
+
+
+
+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)
+