/ 
Langertha-Knarr-1.102
/ knarr

NAME

knarr - Langertha LLM Proxy with Langfuse Tracing

VERSION

version 1.102

SYNOPSIS

knarr <command> [options]

knarr start                                # Start with ./knarr.yaml
knarr start --from-env                     # Auto-detect config from ENV
knarr start --from-env -p 8080 -p 11434   # ENV config, explicit ports
knarr start -c production.yaml -p 9090     # Custom config and port
knarr start -c production.yaml -v          # Custom config, verbose
knarr init > knarr.yaml                    # Generate config from environment
knarr init -e .env -e .env.local           # Scan .env files
knarr init -l 0.0.0.0:8080 -o knarr.yaml   # Listen on all interfaces
knarr models                               # List configured models
knarr models --format json                 # JSON output
knarr check                                # Validate config file

DESCRIPTION

knarr is the command-line interface for Langertha::Knarr, an LLM proxy that accepts requests in OpenAI, Anthropic, Ollama, A2A, ACP, or AG-UI format, routes them to any Langertha backend engine, and traces everything via Langfuse.

The configuration file format, with the environment variable behind each setting, is documented in Langertha::Knarr::Config; the model routing order in "resolve" in Langertha::Knarr::Router. The README of the distribution covers Docker usage, passthrough and every environment variable. Langertha::Knarr documents the server and its Perl API.

Long options can be written with dashes or underscores (--log-file, --log_file) in any position.

COMMANDS

start — Start the proxy server (with config file or --from-env)
init — Scan environment and .env files for API keys, print generated YAML config
models — List all configured and auto-discovered models
check — Validate the config file and report configuration status
container — Deprecated alias for start --from-env -p 8080 -p 11434, the Docker image's own command: always 0.0.0.0:8080 and 0.0.0.0:11434, no options of its own; for other ports use start --from-env -p ...

GLOBAL OPTIONS

Accepted before the subcommand, and after start, check and models (knarr start -c prod.yaml -v); a value given after the subcommand wins.

-c, --config path

Config file path. Defaults to ./knarr.yaml.

-v, --verbose

Enable verbose logging to stderr. Also enabled by KNARR_DEBUG=1.

START OPTIONS

--from-env

Build config from environment variables when no config file is found: one engine per API key found, auto_discover and passthrough on, and OpenAI as the default engine when an OpenAI key is set. This is how the Docker image starts (start --from-env -p 8080 -p 11434).

-p, --port port

Port to listen on, on the host from -H. Repeatable (e.g. -p 8080 -p 11434). Given at least once, it replaces the config's listen:. Without -p Knarr listens on the config's listen: addresses, which default to 127.0.0.1:8080 and 127.0.0.1:11434 (loopback only, also under --from-env).

-H, --host host

Host the -p ports bind to. Defaults to 0.0.0.0. Has no effect without -p.

-w, --workers n

Number of worker processes. Wins over the config's workers: and KNARR_WORKERS; without any of them 1 (one process, nothing forked). Anything but a whole number of 1 or more stops start before it binds anything. With more, Knarr binds the listen addresses, runs auto-discovery and the capability probe once, then forks n workers that accept on the same sockets. The first process stays as their supervisor: it restarts a worker that exits (pausing up to 30 seconds when one keeps dying right after its start or cannot be forked, while the others serve on) and passes SIGTERM/SIGINT on to all of them, exiting once they are gone. Each worker keeps its own sessions: a Raider conversation continues only when its next request reaches the same worker, which nothing guarantees.

-n, --trace-name name

Langfuse trace name. Overrides the config file, LANGFUSE_TRACE_NAME and KNARR_TRACE_NAME.

--log-file path

JSONL log file path for request logging. Overrides KNARR_LOG_FILE and the config file.

--log-dir path

Directory for per-request JSON log files. Overrides KNARR_LOG_DIR and the config file.

INIT OPTIONS

-e, --env-file path

Additional .env file to scan. Repeatable. .env and .env.local in the current directory and $HOME/.env are scanned automatically when they exist.

-l, --listen addr

Listen address to include in generated config. Repeatable. Defaults to 127.0.0.1:8080 and 127.0.0.1:11434; use 0.0.0.0:... for a config that must be reachable from outside, e.g. in a container.

-o, --output path

Write generated config to a file instead of stdout.

MODELS OPTIONS

-f, --format format

Output format: table (default) or json.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-knarr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.