### Clone Repository and Setup Development Environment

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/contributing.md

Clone the repository, navigate to the project directory, add the upstream remote, and start the development server.

```bash
git clone https://github.com/YOUR_USERNAME/borg-ui.git
cd borg-ui
git remote add upstream https://github.com/karanhudia/borg-ui.git
./scripts/dev.sh
```

--------------------------------

### After Create Hook for Repository Setup

Source: https://github.com/karanhudia/borg-ui/blob/main/WORKFLOW.md

Clones the Borg UI repository and installs frontend dependencies if npm is available.

```bash
git clone --depth 1 git@github.com:karanhudia/borg-ui.git .
if command -v npm >/dev/null 2>&1 && [ -f frontend/package-lock.json ]; then
  (cd frontend && npm ci)
fi
```

--------------------------------

### Install and Start Linux Systemd Service

Source: https://github.com/karanhudia/borg-ui/blob/main/agent/README.md

Copy the systemd service unit file, reload the systemd daemon, and then enable and start the Borg UI agent service.

```bash
sudo cp agent/install/systemd/borg-ui-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now borg-ui-agent
```

--------------------------------

### Install Dependencies and Build Docs

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/contributing.md

Navigate to the docs directory, install dependencies using npm, and build the documentation site.

```bash
cd docs
npm ci
npm run build
```

--------------------------------

### Clone and Start Dev Environment

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/development.md

Clone the repository and execute the dev script to start the backend in Docker and the frontend locally. Ensure Docker, Docker Compose, Node.js 20.19+, and Python 3.10+ are installed.

```bash
git clone https://github.com/karanhudia/borg-ui.git
cd borg-ui
./scripts/dev.sh
```

--------------------------------

### Setup Presets Documentation Section

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-06-04-remote-machine-setup-presets.md

Add a section to the SSH keys documentation explaining the available setup presets and their configuration options.

```markdown
## Setup Presets

The deploy dialog includes setup presets for Linux servers, BorgBase,
Hetzner Storage Box, and NAS targets such as Synology and Unraid. Presets
only prefill editable defaults like port, deployment mode, default path,
SSH path prefix, and mount point. Review provider-specific path details in
[Provider Guides](provider-guides) before saving.
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/development.md

Navigate to the frontend directory and run these npm commands for installing dependencies, starting the dev server, type checking, linting, formatting checks, and building the frontend.

```bash
cd frontend
npm install
npm run dev
npm run typecheck
npm run lint
npm run format:check
npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/karanhudia/borg-ui/blob/main/frontend/README.md

Run this command to install all necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Example Post-Backup Script to Start Container

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/docker-hooks.md

This script starts a specified Docker container after a backup has completed. It checks if the container exists (even if stopped) and starts it. Ensure the CONTAINER_NAME environment variable is set or defaults to 'postgres'.

```bash
#!/usr/bin/env bash
set -euo pipefail

container="${CONTAINER_NAME:-postgres}"

if docker ps -a --format '{{.Names}}' | grep -qx "$container"; then
  docker start "$container"
fi
```

--------------------------------

### Install Dependencies and Run Frontend Checks

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/contributing.md

Navigate to the frontend directory, install dependencies, and run type checking, linting, formatting checks, and tests.

```bash
cd frontend
npm install
npm run typecheck
npm run lint
npm run format:check
npm run test
```

--------------------------------

### Clone Borg UI and Install Agent

Source: https://github.com/karanhudia/borg-ui/blob/main/agent/README.md

Use these commands to clone the Borg UI repository and install the agent package into a virtual environment for manual setup.

```bash
git clone https://github.com/karanhudia/borg-ui.git
cd borg-ui
python3.11 -m venv .venv
. .venv/bin/activate
pip install .
```

--------------------------------

### Setup Test Environment

Source: https://github.com/karanhudia/borg-ui/blob/main/tests/README.md

Sets up the necessary test environment for Borg UI. This includes changing the directory and executing a setup script.

```bash
cd /Users/karanhudia/Documents/Projects/borg-ui
./tests/setup_test_env.sh
```

--------------------------------

### Unraid Repository Path Example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/provider-guides.md

Example of a typical repository path configuration for Unraid, using user shares.

```text
Repository path: /mnt/user/backups/borg-repository
```

--------------------------------

### Example Remote Machine Configuration

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/ssh-keys.md

Provides an example of the parameters required when adding a remote machine, including host, port, username, and default path.

```text
Host: backup.example.com
Port: 22
Username: backup
Default path: /backups
```

--------------------------------

### Start Development Server

Source: https://github.com/karanhudia/borg-ui/blob/main/frontend/README.md

Starts the development server for the frontend application. The application will be accessible at http://localhost:7879.

```bash
npm run dev
```

--------------------------------

### Start Manual Backup (Compatibility Alias)

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/api.md

An alias for the /api/backup/start endpoint, accepting the same request body and returning the same response shape. Use this if your client expects 'run' instead of 'start'.

```bash
curl -sS -X POST "$BASE_URL/api/backup/run" \
  -H "X-Borg-Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"repository\":\"$REPOSITORY\"}"
```

--------------------------------

### CodeEditor: pg_dump script example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-31-database-source-preservation.md

Example of a pre-backup script for PostgreSQL, demonstrating how pg_dump writes to a specified directory.

```bash
pg_dump writes to "$BORG_UI_DB_DUMP_DIR"
```

--------------------------------

### NAS Target Path Mapping Example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/provider-guides.md

Example of how to map repository paths for NAS targets like Unraid. Ensure consistency between user share paths and SSH paths.

```text
Host: nas.example.com
Port: 22, or your custom SSH port
Username: the NAS user that can run Borg and access the repository path
Default path: the path Borg UI should browse first
Repository path: the Borg repository path in that same browsing namespace
```

--------------------------------

### Compatibility Alias for Starting Backup

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/api.md

An alias for `/api/backup/start` for clients using `run` instead of `start`. Accepts the same request body and returns the same response shape.

```APIDOC
## POST /api/backup/run

### Description
Compatibility alias for starting a backup job. Accepts the same parameters and returns the same response as `/api/backup/start`.

### Method
POST

### Endpoint
/api/backup/run

### Parameters
#### Request Body
- **repository** (string) - Required - The path of the repository to back up.

### Request Example
```bash
curl -sS -X POST "https://backups.example.com/api/backup/run" \
  -H "X-Borg-Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"repository\":\"/backups/server1\"}"
```

### Response
#### Success Response (200)
- **job_id** (integer) - The ID of the initiated backup job.
- **status** (string) - The initial status of the job (e.g., "pending").
- **message** (string) - A confirmation message.

### Response Example
```json
{
  "job_id": 123,
  "status": "pending",
  "message": "Backup job started"
}
```
```

--------------------------------

### Install Borg UI Agent on Linux

Source: https://github.com/karanhudia/borg-ui/blob/main/agent/README.md

Use this command to install the agent. Ensure the Borg UI server URL is reachable from the client machine. Enrollment tokens are temporary.

```bash
curl -fsSL http://borg-ui-host:8083/agent/install.sh | sudo bash -s \
  --server http://borg-ui-host:8083 \
  --token borgui_enroll_example \
  --name media-node
```

--------------------------------

### macOS launchd Service Installation

Source: https://github.com/karanhudia/borg-ui/blob/main/agent/README.md

Install the Borg UI agent launchd plist file to the system's LaunchDaemons directory and bootstrap the service.

```bash
sudo cp agent/install/launchd/com.borg-ui.agent.plist /Library/LaunchDaemons/
sudo launchctl bootstrap system /Library/LaunchDaemons/com.borg-ui.agent.plist
```

--------------------------------

### Start Borg UI Locally

Source: https://github.com/karanhudia/borg-ui/blob/main/tests/README.md

Starts the Borg UI frontend and backend services locally. The frontend uses npm run dev, and the backend uses uvicorn.

```bash
cd frontend && npm run dev &
cd app && uvicorn main:app --reload
```

--------------------------------

### Install Borg UI from Git Repository

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-22-borg-installer-management.md

Installs the Borg UI from a specific Git reference. Ensure the AGENT_REF variable is correctly set to the desired commit or branch.

```bash
"git+https://github.com/karanhudia/borg-ui.git@${AGENT_REF}"
```

--------------------------------

### Install Borg UI Agent on Linux

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/managed-agents.md

Run this command on the machine to be backed up. It requires root or sudo privileges. The installer configures the agent, registers it with the server, and enables the systemd service.

```bash
curl -fsSL http://borg-ui-host:8083/agent/install.sh | sudo bash -s -- \
  --server http://borg-ui-host:8083 \
  --token borgui_enroll_example \
  --name laptop
```

--------------------------------

### Install Docker CLI

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/docker-hooks.md

Instructions for installing the Docker CLI within the Borg UI container. This is necessary for scripts that need to interact with the Docker daemon.

```text
Settings > System > Packages
```

--------------------------------

### Borg UI Environment Variables Example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/installation.md

An example `.env` file showing common environment variables for configuring Borg UI, including port, PUID, PGID, local storage path, and timezone.

```bash
PORT=8081
PUID=1000
PGID=1000
LOCAL_STORAGE_PATH=/mnt/usb-drive
TZ=America/Chicago
```

--------------------------------

### SSH Repository Path Examples

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/ssh-keys.md

Examples of valid SSH repository path formats for Borg. Includes standard paths, Hetzner Storage Box, and BorgBase formats.

```text
backup@example.com:/backups/laptop
```

```text
ssh://backup@example.com:22/backups/laptop
```

```text
ssh://u123456@u123456.your-storagebox.de:23/./backup-repo
```

```text
ssh://abcd@abcd.repo.borgbase.com/./repo
```

--------------------------------

### Add English Locale Keys for Setup Presets

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-06-04-remote-machine-setup-presets.md

This JSON snippet contains new locale keys for the SSH connection deployment dialog in English. These keys define various setup presets, their descriptions, and default configurations, including options for custom, Linux, BorgBase, Hetzner, and NAS setups, as well as SSH path prefix related strings.

```json
"setupPreset": "Setup preset",
"setupPresetHint": "Pick a documented setup to prefill defaults. You can edit every field before deploying.",
"presetCustom": "Custom setup",
"presetCustomDescription": "Start from the standard SSH defaults.",
"presetCustomDefaults": "Port 22, SFTP deployment enabled",
"presetLinux": "Linux server",
"presetLinuxDescription": "Headless server or VM with normal SSH access.",
"presetLinuxDefaults": "root user, port 22",
"presetBorgBase": "BorgBase",
"presetBorgBaseDescription": "Hosted Borg repository using the /./repo path shape.",
"presetBorgBaseDefaults": "Port 22, SFTP deployment off, default path /./repo",
"presetHetzner": "Hetzner Storage Box",
"presetHetznerDescription": "Storage Box repository over Hetzner's extended SSH service.",
"presetHetznerDefaults": "Port 23, SFTP deployment on, default path /./borg-repository",
"presetNas": "NAS",
"presetNasDescription": "Synology, Unraid, or similar NAS with SSH path mapping.",
"presetNasDefaults": "Port 22, SFTP deployment off, SSH path prefix /volume1",
"sshPathPrefix": "SSH Path Prefix (Optional)",
"sshPathPrefixHelper": "Prefix added when Borg needs a different SSH path than the browsing path, for example /volume1 on Synology."
```

--------------------------------

### Start Development Server

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-30-shared-components-folder.md

Launch the development server to perform manual UI spot checks. This is used to visually verify components after the migration.

```bash
cd frontend && npm run dev
```

--------------------------------

### Agent Binary Detection Payload Example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-22-borg-installer-management.md

An example of the payload structure used by the agent to report detected Borg binaries. It includes version, path, and the source of installation.

```python
{"major": 1, "version": "1.2.8", "path": "/usr/bin/borg", "install_source": "system-package"}
```

--------------------------------

### Lazy Dependency Installation for Frontend

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/specs/2026-05-17-symphony-issue-pr-latency-reduction.md

Replace unconditional 'npm ci' with a policy that installs frontend dependencies only when necessary. This speeds up initial project setup and reduces I/O for non-frontend tasks.

```markdown
- Always clone and start Codex quickly.
- Install frontend dependencies only when:
  - changed files are under `frontend/`,
  - a frontend command is selected by the validation manifest,
  - Storybook/snapshots are required, or
  - the agent explicitly opens a frontend implementation path.
- Keep a host-level npm cache and Python wheel cache. The workspace remains
  disposable, but package downloads should not be repeated from scratch.
- Prefer a full enough git history for merges. The current `--depth 1` clone can
  force unshallow fetches when a feature branch needs `origin/main` merge
  context; a blobless clone with enough refs is usually a better tradeoff than a
  shallow clone that breaks branch ancestry.
```

--------------------------------

### Run Unit Tests

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-21-borg-ui-agent-service-user-hardening.md

Command to execute the unit tests for the service setup module. Use this to verify the implementation of validation logic.

```bash
pytest tests/unit/agent/test_service_setup.py -q
```

--------------------------------

### Implement API Feature Test

Source: https://github.com/karanhudia/borg-ui/blob/main/tests/README.md

Write an API test function in `tests/manual/test_app.py` to verify the functionality of a specific API endpoint. This example tests a GET request to '/api/my-endpoint'.

```python
def test_my_feature(self) -> bool:
    """Test my new feature"""
    try:
        response = self.session.get(
            f"{self.base_url}/api/my-endpoint",
            headers=self.headers,
            timeout=5
        )

        if response.status_code == 200:
            self.log_test("My Feature", True, "Works!")
            return True
        else:
            self.log_test("My Feature", False, f"Failed: {response.status_code}")
            return False
    except Exception as e:
        self.log_test("My Feature", False, f"Error: {e}")
        return False
```

--------------------------------

### Frontend Checks and Build

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/testing.md

Install dependencies, run type checking, linting, format checks, tests, and build the frontend application.

```bash
cd frontend
npm install
npm run typecheck
npm run lint
npm run format:check
npm run test
npm run build
```

--------------------------------

### Install Symphony Reference Implementation

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/symphony.md

Clone and build the official Symphony reference implementation. Ensure local paths are outside the Borg UI repository. This setup requires `mise` for managing Elixir/Erlang versions.

```bash
export SYMPHONY_HOME="$HOME/code/symphony"
export BORG_UI_HOME="$HOME/code/borg-ui"

git clone https://github.com/openai/symphony "$SYMPHONY_HOME"
cd "$SYMPHONY_HOME/elixir"
mise trust
mise install
mise exec -- mix setup
mise exec -- mix build
```

--------------------------------

### Install Pre-Commit Hooks

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/development.md

Install pre-commit and pre-push hooks to automate code quality checks before committing and pushing. Ensure frontend dependencies are installed first.

```bash
pre-commit install --hook-type pre-commit --hook-type pre-push
```

--------------------------------

### Documentation Commands

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/development.md

Change to the docs directory and use npm commands to install dependencies, run the dev server for documentation, and build the documentation.

```bash
cd docs
npm ci
npm run dev
npm run build
```

--------------------------------

### Start Manual Backup

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/api.md

Initiate a backup for an existing repository. Requires an access token and the repository path. The response includes a job_id for polling.

```bash
REPOSITORY="/backups/server1"

START_RESPONSE="$(
  curl -sS -X POST "$BASE_URL/api/backup/start" \
    -H "X-Borg-Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"repository\":\"$REPOSITORY\"}"
)"

JOB_ID="$(printf '%s
' "$START_RESPONSE" | jq -r .job_id)"
printf '%s
' "$START_RESPONSE"
```

--------------------------------

### Start Job Request

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/managed-agent-spec.md

Agent runtime endpoint to signal that a job has started execution.

```json
{
  "started_at": "2026-05-11T12:00:01Z"
}
```

--------------------------------

### Start Job

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/managed-agent-spec.md

Agent runtime endpoint to notify the server that a claimed job has started execution.

```APIDOC
## Start Job

Agent runtime endpoint.

### Method
POST

### Endpoint
/api/agents/jobs/{job_id}/start

### Path Parameters
- **job_id** (integer) - Required - The ID of the job that has started.

### Authentication
Requires agent credentials via `X-Borg-Agent-Authorization` header.

### Request Body
- **started_at** (string) - Required - The ISO 8601 timestamp indicating when the job started.

### Request Example
```json
{
  "started_at": "2026-05-11T12:00:01Z"
}
```
```

--------------------------------

### Database Detail UI Mockup (Original Path Mode)

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-31-database-source-preservation.md

This text-based mockup illustrates the configuration for backing up a database directly from its original path, highlighting advanced settings and warnings.

```text
Capture mode
  ( ) Dump to staging path, recommended
  (o) Back up original path, advanced

Warning
  Borg will read the live database path directly. Use this only when the
  database is stopped, snapshotted, or you have an existing hook that makes the
  files consistent.

Source and backup path
  Source machine       backup-a@server-a.example
  Live database path   /var/lib/postgresql
  Borg will back up    /var/lib/postgresql

Scripts
  ( ) Create generated scripts   (o) Reuse scripts   ( ) Skip scripts
```

--------------------------------

### Install and Register Borg UI Agent as Systemd Service

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/managed-agents.md

Install the Borg UI agent, set up its virtual environment, and register it with the server for systemd service management. This involves creating directories, installing dependencies, and configuring the agent.

```bash
sudo install -d -m 0755 /opt/borg-ui-agent
sudo python3.11 -m venv /opt/borg-ui-agent/.venv
sudo /opt/borg-ui-agent/.venv/bin/pip install .
sudo -u borg-ui-agent /opt/borg-ui-agent/.venv/bin/borg-ui-agent \
  --config /etc/borg-ui-agent/config.toml \
  register \
  --server http://borg-ui-host:7879 \
  --token borgui_enroll_example \
  --name laptop
```

--------------------------------

### Build VitePress Documentation

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-06-03-passkey-ready-https-reverse-proxy-docs.md

Run this command to build the VitePress documentation site. Ensure you are in the `docs` directory.

```bash
cd docs && npm run build
```

--------------------------------

### Start Docker Compose with Profile

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/docker-hooks.md

Use this command to start the Docker Compose services, specifically enabling the 'docker-socket-proxy' profile.

```bash
docker compose --profile docker-socket-proxy up -d
```

--------------------------------

### Setup Test Environment

Source: https://github.com/karanhudia/borg-ui/blob/main/tests/README.md

Execute this script to set up the necessary test environment for archive content tests.

```bash
./tests/setup_test_env.sh
```

--------------------------------

### CodeEditor: PostgreSQL dump cleanup script example

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-31-database-source-preservation.md

Example of a post-backup script for PostgreSQL, showing how to remove the dump directory.

```bash
rm -rf "$BORG_UI_DB_DUMP_DIR"
```

--------------------------------

### Install Borg Backup

Source: https://github.com/karanhudia/borg-ui/blob/main/tests/README.md

Install Borg backup on macOS, Ubuntu/Debian, or Arch Linux to resolve 'borg command not found' errors.

```bash
# macOS
brew install borgbackup

# Ubuntu/Debian
sudo apt install borgbackup

# Arch
sudo pacman -S borg
```

--------------------------------

### Launch Borg UI Development Environment

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-22-remote-direct-backup-execution.md

Start the Borg UI backend and frontend using either the development script or Docker Compose.

```bash
./scripts/dev.sh
```

```bash
docker compose up -d --build
```

--------------------------------

### Search for Documentation References

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/engineering/plans/2026-05-22-remote-direct-backup-execution.md

Run this command to verify that the new documentation sections for 'Remote Direct Backups' and 'repository-side remote Borg path' are correctly indexed.

```bash
rg -n "Remote Direct Backups|repository-side remote Borg path" docs
```

--------------------------------

### Start Borg UI with Docker Compose

Source: https://github.com/karanhudia/borg-ui/blob/main/docs/installation.md

Run this command from the directory containing your docker-compose.yml file to start Borg UI in detached mode.

```bash
docker compose up -d
```