# Environment variables

> Defaults, and what each does. Every page of kelve's docs is listed at https://kelve.ai/llms.txt.

kelve reads these from the environment as it starts. Everything else is set in the app. Set them in your shell's profile, so kelve has them however it starts, even when your agent starts it. After changing one, run `kelve stop`. kelve starts again with the new value the next time you or your agent open something.

If kelve can't use a value, it doesn't start. It says which value and why, such as "KELVE_BIND isn't valid: …".

## Where kelve runs

| Variable | What it does | Default |
|---|---|---|
| `KELVE_URL` | Where you open kelve. kelve makes links from it, and answers at its host. Browsers send any name under `.localhost` to your own computer. kelve also answers at `localhost` on its port. | `http://kelve.localhost:4600`, or `kelve.localhost` on the port in `KELVE_BIND` |
| `KELVE_BIND` | The address kelve listens on. | `127.0.0.1:4600` |
| `KELVE_NO_BROWSER` | When it's set to anything, kelve never opens a browser. Run `kelve serve` in a terminal instead. It shows each sign-in link there. | Not set |

## What it keeps, and where

| Variable | What it does | Default |
|---|---|---|
| `KELVE_DATA` | kelve's data folder. It holds kelve's stores, its sealing key and its log. It holds your own notes too, unless you chose a folder for them. | The folder the secret is in, `~/.config/kelve` |
| `KELVE_STORE` | The store's file. When it's set, kelve uses that file, whatever the graph. | One for each shared graph, in the data folder. `kelve.db` is for kelve's own, and `kelve-<address>.db` for any other, such as `kelve-localhost-4620.db` |
| `KELVE_SECRET_FILE` | The secret the command line and your agent's tools use to reach kelve. Unless `KELVE_DATA` is set, the data folder moves with it. | `~/.config/kelve/secret` |
| `KELVE_SECRET_KEY` | 64 hex characters (`openssl rand -hex 32`). Seals the shared graph's key before it's kept. | Made the first time, in `secret.key` in the data folder |

`~/.config` is `$XDG_CONFIG_HOME` when that's set, and `%APPDATA%` on Windows.

## The shared graph

| Variable | What it does | Default |
|---|---|---|
| `KELVE_GRAPH_URL` | The shared graph. `off` uses none. Each graph has its own store, with its own sign-in and what kelve kept from it. Change it to change graphs. Change it back to find everything as it was. | `https://graph.kelve.ai` |
| `KELVE_GRAPH_KEY` | A key for adding to the graph, in place of signing in. It wins over signing in. | Not set |
| `KELVE_WRITE_REAL_GRAPH` | `1` lets a kelve built from source add to `graph.kelve.ai`. Without it, such a kelve only reads it. It adds to any other graph either way. | Not set |

[Run your own graph](/docs/own-graph/) has more.

## Lessons

| Variable | What it does | Default |
|---|---|---|
| `KELVE_LESSON_HOLD` | How long, in seconds, a lesson your agent wrote waits before it goes to the shared graph, so you can stop it. From `0` to 30 days. For trying lessons out. | `86400`, a day |
| `KELVE_HOLD_BACK` | How often a lesson that fits is held back from your agent, in thousandths, from `0` to `1000`. Holding some back lets the graph tell whether lessons help. Only a lesson already given 100 times across everyone is ever held back. | `50`, one in twenty |

## Your agent

| Variable | What it does | Default |
|---|---|---|
| `KELVE_CLAUDE_DIR` | Claude Code's folder, whose `settings.json` gets kelve's hook. | Claude Code's own `CLAUDE_CONFIG_DIR`, or `~/.claude` |
| `KELVE_AGENTS_HOME` | The home folder other agents' settings are in. kelve uses it for their hooks, and for Cursor's `.cursor/mcp.json` when `kelve setup` connects it. | Your home folder |

## Updates

| Variable | What it does | Default |
|---|---|---|
| `KELVE_UPDATES` | Where kelve asks, once a day, whether a newer version is out. `off` stops it. kelve and your agent then never hear of a newer one, but [`kelve update`](/docs/update-uninstall/) still works when you run it. For a mirror, give an address that answers in the shape of GitHub's API, and kelve asks there instead. | GitHub, where kelve's releases are. A kelve built from source doesn't ask. |

## Counts

| Variable | What it does | Default |
|---|---|---|
| `DO_NOT_TRACK` | When it's set to anything but `0`, `false`, `no` or `off`, kelve never sends its anonymous weekly counts, whatever you chose. Settings say so. | Not set |
| `KELVE_TELEMETRY` | `off` does the same. | Not set |

## The command line

| Variable | What it does | Default |
|---|---|---|
| `RUST_LOG` | How much kelve logs, like `info` or `kelve_server=debug`. | `info`, with less from the libraries kelve uses |
| `NO_COLOR` | When it's set to anything, the command line prints without colour. | Not set |

## Installing

The installer reads these, not kelve.

| Variable | What it does | Default |
|---|---|---|
| `KELVE_INSTALL_DIR` | Where the installer puts `kelve`. | `~/.local/bin`, or `%LOCALAPPDATA%\kelve\bin` on Windows |
| `KELVE_RELEASES` | Where `install.sh` downloads kelve from, such as a release served while developing kelve. The Windows installer doesn't read it. | kelve's newest release on GitHub |

## Developing kelve

| Variable | What it does | Default |
|---|---|---|
| `KELVE_PICKER` | A program kelve runs in place of your system's picker. kelve gives it `folder` or `file`, and it prints the path chosen. For kelve's browser tests. | Not set |
| `KELVE_DEFAULT_GRAPH_URL` | The graph a build uses when `KELVE_GRAPH_URL` isn't set. kelve reads it as it's built, not as it starts. | `https://graph.kelve.ai` |

Keys given in the environment are never kept in kelve's store.
