Dark-Alex-17/coyote
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

Updated docs again

Alex Clarke
2026-05-05 12:58:57 -06:00
parent 461a690670
commit 0e03d7d32d
4 changed files with 183 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Home.md
+3 -4
@@ -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.
docs/Getting-Started.md
+7 -9
@@ -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); <br>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 `<max_width>` |
| `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. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul> |
| `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 |
docs/Installation.md
+13 -15
@@ -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
docs/Vault.md
+160
@@ -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
<!--toc:start-->
- [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)
<!--toc:end-->
---
# 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 <SECRET_NAME> Add a secret to the Loki vault
--get-secret <SECRET_NAME> Decrypt a secret from the Loki vault and print the plaintext
--update-secret <SECRET_NAME> Update an existing secret in the Loki vault
--delete-secret <SECRET_NAME> 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 | |
| `<agent>/tools.<py/sh>` | 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
`<agent>/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 `<agent>/tools.<py/sh>` 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)