Startup & Access

Backlog.md includes a modern Web interface for intuitively managing tasks, boards, milestones, and documents in the browser. Start it with the backlog browser command.

Starting the Web Server

Open a terminal, enter the Backlog.md project directory, and run:

backlog browser

The server binds to 127.0.0.1 (loopback) by default and automatically opens the interface in the default browser after starting. The console prints something like:

🚀 Backlog Web UI running at http://localhost:6420

By default it only listens to local requests; other devices on the same network cannot access it directly.

Command-Line Options

Specifying a Port

If the default port 6420 is already in use, specify another port with --port:

backlog browser --port 8080

After startup, open http://localhost:8080 in the browser.

Automatic Port Fallback

By default (config item autoPort: true), if the default port is occupied, the server automatically scans for the next available port and prints the real address in the console. You do not need to specify one manually, and it will not exit with an error:

🚀 Backlog Web UI running at http://localhost:6421

Automatic scanning only accepts ports in the user port range (1024–65535) and refuses random high ports assigned by the OS for ephemeral use. If autoPort is set to false, a port conflict will produce an EADDRINUSE error (use --port to specify one explicitly). This switch can also be toggled in the Web interface "Settings" panel.

Disable Auto-Open

If you do not want the browser window to pop up automatically (for example on a remote server or in a CI environment), add --no-open:

backlog browser --no-open

In this case, copy the address printed in the console and open it manually.

Specifying the Bind Host

By default the Web server binds only to 127.0.0.1, which is suitable for local development. To allow access from other devices on the LAN, use --host:

# Listen on all interfaces (open LAN access)
backlog browser --host 0.0.0.0

When binding to a wildcard, the console prints the specific LAN IPv4 address and notes that the API is currently unauthenticated. The browser automatically opens the first available LAN address. You can also bind to a specific network interface:

backlog browser --host 192.168.1.100

Using a Custom Browser

In devcontainers or containers without a default browser, you can specify the launch command via the BROWSER environment variable:

BROWSER=/usr/bin/chromium backlog browser

BROWSER is treated as a single executable path (surrounding quotes are stripped; it is not split or shell-evaluated), and the URL is passed as a separate argument. When unset, the platform default is used: open (macOS), cmd /c start (Windows), xdg-open (Linux).

Combining Options

backlog browser --port 3000 --no-open
BROWSER=/usr/bin/chromium backlog browser --host 127.0.0.1 --port 8080

Technical Features

The Web interface is built with the following technologies for a smooth experience:

React: component-based interactive UI with no full-page reloads.
Tailwind CSS v4: modern styling system with a clean, consistent look.
Responsive layout: automatically adapts to desktop and mobile screen sizes.
Dark mode: follows the system theme automatically, or can be switched manually between light and dark.

Real-Time Sync

The Web interface stays in sync with local Markdown files:

Changes to task status or content in the browser are written back to the corresponding Markdown files.
Changes made in external editors (such as VS Code or Vim) are reflected in the Web interface instantly.
No manual refresh is needed; all views update in real time via WebSocket.

Interface Layout

The Web interface uses a classic left-right layout:

Left sidebar: fixed width, showing the navigation menu and file tree.
Right content area: takes the remaining space, showing tasks, boards, documents, or Wiki content.

The right edge of the sidebar is a full-height draggable handle. Hover over it until the cursor becomes a left-right arrow, then drag to adjust the sidebar width. While dragging, a blue ghost bar previews the final position; releasing the mouse applies the width immediately and saves it to browser local storage (localStorage) so it is restored next time.

Minimum width is 200px, preventing the sidebar from becoming invisible.
Maximum width is 500px, avoiding excessive use of content area space.

A collapse/expand button (arrow icon) is located on the right side of the sidebar. Click it to collapse the sidebar to a narrow icon-only mode; click again to expand. Collapse state and width settings are both saved to localStorage.

Stopping the Server

Press Ctrl + C in the terminal running backlog browser to stop the Web server. All saved changes have already been written to the filesystem, so no data is lost.

Loading Indicators

Loading feedback in the Web interface has two layers:

Initial load: the board area shows a skeleton screen that matches the real column layout (breathing-animation ghost columns), with a loading spinner in the center. The uninitialized-project waiting screen also shows a loading spinner.
Background indexing: while background work such as cross-branch indexing runs, a status chip appears in the header on the right (showing the current stage text; hover for full details), and a sweeping progress bar runs below the header. The already-loaded board and tree remain interactive and are not covered by the skeleton screen.

Loading animations still play when the system has "reduce motion" enabled—loading progress is essential feedback rather than decoration; a static spinner is easily mistaken for a freeze on remote desktops and virtual machines.

Running as a Persistent Service

backlog browser --no-open starts only the service without opening the browser, making it suitable for registering as a startup persistent service (doc-003). Key point: one independent service and port per project, and the working directory must point to the project root.

Linux (systemd user service): create ~/.config/systemd/user/backlog-browser-<project>.service with ExecStart set to backlog browser --no-open --port <port> and Restart=on-failure; run loginctl enable-linger so it starts on boot without a login session. For many projects, use a template unit backlog-browser@.service.
macOS (launchd): place a uniquely labeled plist in ~/Library/LaunchAgents/ with RunAtLoad and KeepAlive. Note that Apple Silicon and Intel binaries are at /opt/homebrew/bin/backlog and /usr/local/bin/backlog respectively.
Windows: use Task Scheduler (New-ScheduledTaskAction, triggered by -AtLogOn) for login startup. For always-on service without a logged-in user, wrap it with NSSM as a real Windows service to get automatic restart.

Launch & Access