~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
#!/bin/bash
# Restart the LDR dev server.
#
# Usage:
# scripts/dev/restart_server.sh [PORT] [--debug] [--tmp]
#
# PORT Optional port (default: 5000). Passed via LDR_WEB_PORT.
# --debug DEBUG logging (LDR_APP_DEBUG=true, LDR_LOG_SETTINGS=summary).
# WARNING: debug logs may contain sensitive data (queries,
# answers, API responses) — local dev / feature testing only,
# never production or real user data.
# --tmp Disposable instance: point LDR_DATA_DIR at a throwaway dir
# (default /tmp/ldr-test) so encrypted user DBs, the auth DB,
# library, logs, research_outputs etc. land OUTSIDE your real
# data dir (~/.local/share/local-deep-research). Override the
# location by exporting LDR_DATA_DIR before running. Reuses one
# dir (doesn't accumulate throwaway databases). To start from a
# clean slate, wipe LDR_DATA_DIR yourself first (e.g.
# `rm -rf "$LDR_DATA_DIR"`) — this script never deletes data.
#
# Only the instance listening on the target PORT is stopped, so multiple
# instances on different ports (e.g. several agents each on their own port)
# coexist — restarting one does not kill the others.
#
# The server makes itself non-dumpable at startup, so on Linux a same-user
# `fuser PORT/tcp`, `lsof -i` or `ss -p` cannot see which process owns the
# port (its /proc fd entries become root-only). This script therefore
# starts the server in its own process group, records that group in
# ${XDG_RUNTIME_DIR:-/tmp}/ldr_server_PORT.pid, and on the next restart stops
# the group only after checking it is an LDR server launched for this PORT.
# It exits non-zero if the port is still taken or the new server fails to
# start listening.
#
# Referenced in:
# - tests/api_tests_with_login/README.md
# - examples/api_usage/http/README.md
# - examples/api_usage/http/advanced/simple_http_example.py
# Do not delete without updating those references.
set -u
# No job control, even when invoked from `bash -i`, with `set -m`, or with
# monitor in an exported SHELLOPTS. With job control every background job
# leads its own process group, and util-linux setsid then forks instead of
# exec'ing, so $! would no longer be the server's process group.
set +m
usage() {
cat <<'EOF'
Restart the LDR dev server.
Usage:
scripts/dev/restart_server.sh [PORT] [--debug] [--tmp]
PORT Optional port (default: 5000).
--debug DEBUG logging (may log sensitive data; local dev only).
--tmp Disposable instance: LDR_DATA_DIR -> /tmp/ldr-test (override by
exporting LDR_DATA_DIR). Keeps test data out of your real dir.
This script never deletes data; wipe LDR_DATA_DIR yourself to
start from a clean slate.
--test Alias for --tmp.
Only the instance on the target PORT is stopped; instances on other ports
keep running.
EOF
}
PORT=5000
debug=0
use_tmp=0
for arg in "$@"; do
case "$arg" in
--debug) debug=1 ;;
--tmp|--test) use_tmp=1 ;;
-h|--help) usage; exit 0 ;;
''|*[!0-9]*) echo "Unknown argument: $arg" >&2; usage >&2; exit 2 ;;
*) PORT="$arg" ;;
esac
done
SERVER_PATTERN="local_deep_research.web.app"
PID_DIR="${XDG_RUNTIME_DIR:-/tmp}"
[ -d "${PID_DIR}" ] || PID_DIR=/tmp
PID_FILE="${PID_DIR}/ldr_server_${PORT}.pid"
LOG_FILE="/tmp/ldr_server_${PORT}.log"
# Seconds to wait for the old server to exit and for the new one to listen.
STOP_TIMEOUT=15
START_TIMEOUT="${LDR_RESTART_START_TIMEOUT:-90}"
case "${START_TIMEOUT}" in
''|*[!0-9]*|0)
echo "Error: LDR_RESTART_START_TIMEOUT must be a positive whole number of seconds, got '${START_TIMEOUT}'." >&2
exit 2
;;
esac
# Probe host: LDR_WEB_HOST as the server will see it, without IPv6 brackets.
# A wildcard bind accepts connections on loopback. The host can also come
# from the web.host setting or a legacy server_config.json in the data dir;
# this script does not read those, so export LDR_WEB_HOST if you set the
# host there to something other than a wildcard or loopback address.
PROBE_HOST="${LDR_WEB_HOST:-127.0.0.1}"
PROBE_HOST="${PROBE_HOST#[}"
PROBE_HOST="${PROBE_HOST%]}"
case "${PROBE_HOST}" in
0.0.0.0|'') PROBE_HOST=127.0.0.1 ;;
::) PROBE_HOST=::1 ;;
esac
# True when something accepts TCP connections on PORT. Uses bash's
# /dev/tcp, which needs no access to the listening process's /proc entries.
# Bounded by `timeout` where available, since a filtered address can make
# the connect hang.
port_in_use() {
# $1/$2 expand in the child bash, which gets host and port as arguments.
# shellcheck disable=SC2016
local probe='exec 3<>"/dev/tcp/$1/$2"'
if command -v timeout >/dev/null 2>&1; then
timeout 2 bash -c "${probe}" _ "${PROBE_HOST}" "${PORT}" 2>/dev/null
else
bash -c "${probe}" _ "${PROBE_HOST}" "${PORT}" 2>/dev/null
fi
}
# True while any process in process group $1 is alive.
group_alive() {
kill -0 -- "-$1" 2>/dev/null
}
# True when the pidfile may be trusted: a regular file, not a symlink, and
# owned by the current user (a shared /tmp lets others pre-create it).
pid_file_trusted() {
[ -f "${PID_FILE}" ] && [ ! -L "${PID_FILE}" ] && [ -O "${PID_FILE}" ]
}
# True when some process in group $1 was launched for this PORT. The
# server itself is non-dumpable, so its environ is root-only, but the
# `pdm run` / `env` processes above it in the group stay readable.
group_serves_port() {
local pid
for pid in $(pgrep -g "$1" 2>/dev/null); do
if tr '\0' '\n' 2>/dev/null < "/proc/${pid}/environ" \
| grep -qxF "LDR_WEB_PORT=${PORT}"; then
return 0
fi
done
return 1
}
# Stop the server this script launched for PORT, by the process group
# recorded in PID_FILE. Nothing is signalled unless the group runs
# SERVER_PATTERN and was launched with LDR_WEB_PORT=PORT, so a stale or
# planted pidfile cannot stop another port's server or an unrelated group.
stop_recorded_server() {
local pgid
[ -e "${PID_FILE}" ] || [ -L "${PID_FILE}" ] || return 0
if ! pid_file_trusted; then
echo "Warning: ignoring ${PID_FILE}: not a regular file owned by $(id -un)." >&2
return 0
fi
pgid=$(cat "${PID_FILE}" 2>/dev/null)
case "${pgid}" in
''|*[!0-9]*) rm -f "${PID_FILE}"; return 0 ;;
esac
if [ "${pgid}" -le 1 ]; then
rm -f "${PID_FILE}"
return 0
fi
if ! pgrep -g "${pgid}" -f "${SERVER_PATTERN}" >/dev/null 2>&1; then
rm -f "${PID_FILE}"
return 0
fi
if ! group_serves_port "${pgid}"; then
echo "Warning: process group ${pgid} in ${PID_FILE} is not an LDR server for port ${PORT}; not stopping it." >&2
rm -f "${PID_FILE}"
return 0
fi
echo "Stopping LDR server process group ${pgid} on port ${PORT}..."
kill -TERM -- "-${pgid}" 2>/dev/null
local i
for ((i = 0; i < STOP_TIMEOUT; i++)); do
group_alive "${pgid}" || break
sleep 1
done
if group_alive "${pgid}"; then
echo "Server did not exit after ${STOP_TIMEOUT}s; sending SIGKILL." >&2
kill -KILL -- "-${pgid}" 2>/dev/null
sleep 1
fi
rm -f "${PID_FILE}"
}
# Record process group $1 in PID_FILE without following a planted symlink
# or overwriting a file another user owns.
write_pid_file() {
if [ -L "${PID_FILE}" ] || { [ -e "${PID_FILE}" ] && ! pid_file_trusted; }; then
echo "Warning: not recording PID in ${PID_FILE}: not a regular file owned by $(id -un)." >&2
return 1
fi
rm -f "${PID_FILE}"
(set -C; echo "$1" > "${PID_FILE}") 2>/dev/null || {
echo "Warning: could not write ${PID_FILE}." >&2
return 1
}
}
echo "Stopping existing LDR server on port ${PORT} (if any)..."
stop_recorded_server
# A server this script did not start (or one started before it recorded
# PIDs) is not in PID_FILE. Try a port-scoped stop; on Linux this only
# finds a non-dumpable LDR server when run as root.
if port_in_use; then
if command -v fuser >/dev/null 2>&1; then
fuser -k "${PORT}/tcp" >/dev/null 2>&1
elif command -v lsof >/dev/null 2>&1; then
pids=$(lsof -ti "tcp:${PORT}" -sTCP:LISTEN 2>/dev/null)
if [ -n "${pids}" ]; then
# $pids may be several PIDs; word-splitting is intended here.
# shellcheck disable=SC2086
kill ${pids} 2>/dev/null
fi
fi
for ((i = 0; i < STOP_TIMEOUT; i++)); do
port_in_use || break
sleep 1
done
fi
if port_in_use; then
echo "Error: port ${PORT} is still in use; not starting a new server." >&2
echo "It is held by a process this script did not start, and on Linux a" >&2
echo "running LDR server is non-dumpable, so same-user fuser/lsof cannot" >&2
echo "see it. Find and stop it with one of:" >&2
echo " pgrep -af '${SERVER_PATTERN}|ldr-web' # then: kill <PID>" >&2
echo " sudo fuser -k ${PORT}/tcp" >&2
echo "or pass a different PORT." >&2
exit 1
fi
echo "Port ${PORT} is free."
# Change to the project root.
cd "$(dirname "$0")/../.." || exit 1
# --- environment for the launched server -------------------------------------
env_args=(LDR_WEB_PORT="${PORT}")
if [ "$use_tmp" -eq 1 ]; then
: "${LDR_DATA_DIR:=/tmp/ldr-test}"
mkdir -p "$LDR_DATA_DIR"
echo "Using disposable LDR_DATA_DIR=$LDR_DATA_DIR"
env_args+=(LDR_DATA_DIR="${LDR_DATA_DIR}")
fi
if [ "$debug" -eq 1 ]; then
env_args+=(LDR_APP_DEBUG=true LDR_LOG_SETTINGS=summary)
fi
if [ "$debug" -eq 1 ]; then
echo "Starting LDR server on port ${PORT} (DEBUG)..."
else
echo "Starting LDR server on port ${PORT}..."
fi
# Start server in background and detach from terminal. Backgrounding nohup
# directly (rather than wrapping in an extra `( ... & ) &` subshell) means
# $! captures the real launcher PID, not a transient subshell that has
# already exited. nohup ignores SIGHUP, so the server survives the launcher
# exiting and is reparented to init. setsid (where available) puts the
# server and its `pdm run` parent in a new process group. Because job
# control is off (`set +m` above), the background job does not lead a
# group, so setsid exec's in place and the new group's ID is $!; this is
# checked once the server is up, before the next restart relies on it.
launcher=(nohup)
if command -v setsid >/dev/null 2>&1; then
launcher+=(setsid)
fi
"${launcher[@]}" env "${env_args[@]}" pdm run python -m local_deep_research.web.app > "${LOG_FILE}" 2>&1 &
SERVER_PID=$!
if [ "${#launcher[@]}" -gt 1 ]; then
write_pid_file "${SERVER_PID}"
fi
# Wait until the new server accepts connections; fail loudly if it exits
# first (e.g. the port was taken, or startup refused) or never listens.
started=0
for ((i = 0; i < START_TIMEOUT; i++)); do
if ! kill -0 "${SERVER_PID}" 2>/dev/null; then
break
fi
if port_in_use; then
started=1
break
fi
sleep 1
done
if [ "${started}" -ne 1 ]; then
if kill -0 "${SERVER_PID}" 2>/dev/null; then
echo "Error: server (PID ${SERVER_PID}) is not listening on port ${PORT} after ${START_TIMEOUT}s." >&2
echo "It is still running; set LDR_RESTART_START_TIMEOUT to wait longer." >&2
else
echo "Error: server failed to start on port ${PORT}." >&2
rm -f "${PID_FILE}"
fi
echo "--- last 40 lines of ${LOG_FILE} ---" >&2
tail -40 "${LOG_FILE}" >&2 2>/dev/null
exit 1
fi
# Confirm the recorded group really is $!; if setsid forked anyway, the
# pidfile would name a dead group, so drop it and say how to stop instead.
if pid_file_trusted; then
pgid=$(ps -o pgid= -p "${SERVER_PID}" 2>/dev/null | tr -d ' ')
if [ "${pgid}" != "${SERVER_PID}" ]; then
echo "Warning: server is not in process group ${SERVER_PID}; next restart cannot stop it automatically." >&2
rm -f "${PID_FILE}"
fi
fi
echo "Server started. PID: ${SERVER_PID}"
echo "Logs: ${LOG_FILE}"
echo "URL: http://127.0.0.1:${PORT}"
if [ "$debug" -eq 1 ]; then
echo ""
echo "WARNING: DEBUG mode — logs may contain sensitive data; local dev only."
fi
echo ""
echo "To view logs: tail -f ${LOG_FILE}"
if pid_file_trusted; then
echo "To stop server: kill -TERM -- -${SERVER_PID} (or rerun this script)"
else
echo "To stop server: pkill -f '${SERVER_PATTERN}' (stops every instance)"
fi
exit 0