---
title: Fine-tuning on your own sessions
description: Turn your good venom sessions into a redacted fine-tuning dataset with venom finetune export and train a local LoRA with venom finetune train or make finetune. Off by default, nothing is uploaded.
section: evals
order: 50
audience: [user, operator]
sources: [docs/finetune.md, cli/src/finetune-cli.ts, cli/src/export-traces-cli.ts, cli/src/finetune.ts, docs/venom-config.schema.json, Makefile]
features: [evals.finetune]
---

Venom can turn the sessions you have already run into a fine-tuning dataset for your own local models, and start a local fine-tune with a trainer you installed. It is off by default, redacts before it writes anything, and never uploads: the dataset and the adapter stay in the directory you name. It works with the network unplugged.

## Turn it on {#enable}

```yaml
# ~/.venom/config.yaml (or ./venom.yaml)
finetune:
  enabled: true
  since: 2026-10-23          # optional: sessions older than this are never read
  trainer: auto              # unsloth | axolotl | llama-finetune; auto = the first on PATH
  base_model: /models/Qwen3-8B
```

| Key | Type | Default | What it does |
|---|---|---|---|
| `finetune.enabled` | boolean | `false` | Lets `venom finetune export` (and `venom export-traces`) read your saved sessions. Until it is `true`, `export`, `train` and `export-traces` refuse with exit 3 and read nothing. |
| `finetune.since` | date string | none | A floor: sessions last modified before it are never read, whatever `--since` says. Set it when you turn the switch on, so older work isn't swept up. |
| `finetune.trainer` | string | `auto` | `unsloth`, `axolotl` or `llama-finetune`: the trainer `train` runs. `auto` takes the first one on `PATH`. |
| `finetune.base_model` | string | none | The local base model the trainer starts from: a directory, or a GGUF file for `llama-finetune`. Required by `train`. |

The `finetune` block is per machine and per user. Check it with:

```bash
venom finetune status
```

`status` prints whether export is on, the floor, the trainer found, and that nothing is uploaded. It never opens a session, so anyone on the machine can run it.

## Export a dataset {#export}

```bash
venom finetune export --out ~/ft/venom --since 30d --min-quality 0.75
```

| Flag | What it does | Default |
|---|---|---|
| `--out <dir>` | Where the dataset goes (required). Created mode 0700, files 0600. | none |
| `--since <7d\|date>` | Only sessions modified since then (never before `finetune.since`). | all |
| `--min-quality <0-1>` | Drop sessions scoring below it. | `0.5` |

`venom export-traces` is the same command. It writes three files:

| File | What |
|---|---|
| `openai.jsonl` | One session per line, `{messages, tools}`, in OpenAI chat format with tool calls. |
| `sharegpt.jsonl` | The same sessions as ShareGPT conversations. |
| `manifest.json` | What to review before training: each kept session with its quality score, tool-call count, test result and a redacted 120-character preview of its first prompt; what was rejected and why; and the near-duplicates dropped. It says `scrubbed: true`. |

Only sessions that met the outcome bar are included: every assistant reply finished without an error or abort, the run ended on an answer, you denied no tool call, the last test command passed, and nothing was rolled back (`/undo`, a checkpoint restore, `/rewind`). The quality score is 0.5, plus 0.25 for a recorded passing test run, plus 0.25 times the share of tool calls that succeeded. Near-duplicates (same prompts, same tool sequence) are kept once.

## Redaction {#redaction}

Everything is redacted before it is written, in this order:

1. the trace scrubber that `venom export` uses;
2. environment values: every secret-named variable and any long opaque value, written as `<env:NAME>`;
3. key patterns and secret-named assignments (`*_KEY=...`, `"api_key": "..."`);
4. the share redactor that `venom session share` uses: provider key shapes, JWTs, PEM blocks, URL passwords, `Bearer` tokens, credential-named values, the values in the project's `.env`, long hex strings and the home directory;
5. email addresses, as `<email>`, and any user's home directory (`/Users/x`, `/home/x`, `C:\Users\x`), as `~`.

Secrets from the vault never appear in a transcript as values (it stores `{{secret:NAME}}` references), so they come through as references.

> [!WARNING]
> Redaction is pattern based. Read the manifest and a sample of the JSONL before you train on it.

## Train locally {#train}

```bash
venom finetune train --data ~/ft/venom              # or: make finetune DATA=~/ft/venom
venom finetune train --data ~/ft/venom --dry-run    # print the command only
make finetune DATA=~/ft/venom ARGS="--dry-run"
```

| Flag | What it does | Default |
|---|---|---|
| `--data <dir>` | The directory `export` wrote (required). `make finetune` takes it as `DATA=`. | none |
| `--out <dir>` | Where the adapter goes. | `<data>/adapter` |
| `--dry-run` | Print the trainer command and exit. | off |

`train` finds the trainer on `PATH` and runs it with `HF_HUB_OFFLINE=1` and `TRANSFORMERS_OFFLINE=1`. Venom does not install trainers, download models or start a GPU job on its own.

| Trainer | Command it runs |
|---|---|
| `llama-finetune` (llama.cpp) | `llama-finetune --model-base <gguf> --train-data openai.jsonl --lora-out <out>/lora.gguf` |
| `axolotl` | `axolotl train axolotl.yaml` (venom writes the YAML next to the dataset: LoRA, chat template) |
| `unsloth` | `unsloth train --model <dir> --dataset openai.jsonl --output <out>` |

Trainer command lines change between versions. If yours differs, take the paths from `--dry-run` and run your own recipe. Serve the result with Ollama or llama.cpp and add it to your orchestrator config like any local model.

## Exit codes {#errors}

| Code | Meaning |
|---|---|
| 0 | Done (or `status`, `--dry-run`, help). |
| 2 | A usage error: `--data` missing, no `openai.jsonl` and `manifest.json` in it, a manifest that doesn't say `scrubbed: true`, no `finetune.base_model`, an unknown trainer or subcommand. `make finetune` without `DATA=` also exits 2. |
| 3 | `finetune.enabled` is not `true`. |
| 4 | No trainer installed; nothing was run. The export still works. |

## Venom Cloud {#cloud}

There is no cloud part. Sessions stay on the machine that ran them, and the export reads local files. No session content is sent to the cloud.

## Related

- [venom.yaml reference](/docs/configuration/venom-yaml.md).
- [Models, offline mode and tool billing](/docs/configuration/models.md): adding a local model.
- [Sessions](/docs/cli/sessions.md): where sessions are saved.
