Configuration

Change the interface language in F9 → Options → Language. Choose English, Simplified Chinese, Portuguese (Portugal), Spanish, or Russian, then press Enter; Esc cancels. The choice is saved in config.toml as language = "en", "zh-CN", "pt", "es", or "ru". BORG_LANGUAGE overrides the saved setting. If neither is set, Borg follows LC_ALL, LC_MESSAGES, or LANG, and uses English for languages it does not support. Commands, paths, file names, and keyboard shortcuts are never translated. The language menu on this website changes the guide’s language separately.

Settings are saved in ~/.config/borg-commander/config.toml, or in the folder set by $XDG_CONFIG_HOME or $BORG_CONFIG_DIR. F9 → Options → Settings shows them as checkboxes; Space or a click toggles a setting and saves it right away. Esc closes the window. Borg reads the file setting by setting. A setting it does not have, or a value it cannot use, costs only that setting: Borg says which line it is when it starts and uses its default there. When Borg saves a setting it changes that one and keeps the rest of the file, with your comments, as you wrote it. A setting from an older version is read as what replaced it and leaves the file at the next save. A file that is not TOML at all starts Borg on its defaults, and the first setting you then save keeps that file beside the new one as config-unreadable.toml.

theme = "neon"              # midnight, aurora, neon, classic, paper, ember, or your own
icon-style = "auto"         # auto, nerd, or portable; Ghostty gets rich icons automatically
icon-spacing = 1            # spaces after an icon, 1 to 3
status-line = true
menu-bar = false            # keep the menu bar visible
show-hidden = false
return-to-panels = true    # return after commands launched from the panels
restore-terminal = false    # bring back the shell scrollback on the next start
screensaver = true          # one of five animations, picked at random
screensaver-after = 300     # seconds of idle time
update-check = true         # offer a new release once a day
start-service = true        # start the background service when Borg opens
graphics = "auto"           # auto, kitty, sixel, iterm or off
relay = "wss://relay.example.com"  # the relay for borg cloud

[plugins]
git = true
system = true
docker = true
docker-console = true       # the command line follows container panels into the container
agent-log = true            # keep a log of what agents do in each session
agent-cloud = true          # paired computers reach this borg through borg cloud
agent-ask-reads = false     # reads from another computer wait for approval

[search]
exclude = ["*.min.js", "fixtures/large"]  # paths below the search folder, as in .gitignore
artifacts = true            # leave out node_modules, Cargo's target and cache-tagged folders
ignore-files = true         # follow .gitignore, .ignore, .rgignore and .borgignore
history = true              # remember searches for Ctrl-P and Ctrl-N

[index]
roots = ["~/Projects"]      # folders indexed for instant search
refresh-minutes = 15        # rebuild an index once it is this old

[folders]
hotlist = ["~/Projects", "/srv/www"]  # pinned with Ctrl-\ and Insert
history = true              # remember the folders the panels open

[network]
proxy-ca = "~/dev-ca"       # the CA folder for captures through Borg's proxy
keep-free-mib = 1024        # stop captures before the disk has less than this free

[watch]
on = false                  # watch what starts, in the background service
freeze = true               # stop a process a rule is sure about
learning-days = 7           # learn what is normal here before freezing anything, 365 at most
alerts-per-minute = 20      # processes written about before Borg only counts them
freezes-per-minute = 5
keep-running = ["backup-agent"]  # programs Borg never freezes

[[watch.allow]]
program = "/bin/sh"         # allowed starts: program, parent, user, or any of them together
parent = "nginx"

[watch.notify.telegram]     # send alerts as they happen, see Alerts off the machine
token = "123456:ABC"
chat = "123456789"

In a local terminal with true color, Borg starts with a short glitch animation of its logo; any key or click skips it. Over SSH, and in terminals without true color, it opens straight to the panels.

After screensaver-after seconds without input, Borg shows one of five screensavers, picked at random: a cube spinning in a starfield, the glitching logo, a clock in the logo’s block letters that tears apart as each minute turns, the logo swirling out into a spiral galaxy and back, or the logo rebuilt plank by plank while the old planks gather into a second logo below it. Any key or click brings the panels back, and that key does nothing else. An agent’s approval ends the screensaver by itself, so it never waits behind one.

Custom themes go in ~/.config/borg-commander/themes/. A theme can extend a built-in one:

name = "Deep Space"
extends = "neon"

[styles]
cursor = { fg = "#0b0b16", bg = "#00e5ff", bold = true }
dir = { fg = "#b388ff", bold = true }

Borg’s files

Panel folders, cursor positions, the split, listing modes, and sorting are saved in the state folder, ~/.local/state/borg-commander, or in the folder set by $XDG_STATE_HOME or $BORG_STATE_DIR.

While it runs, Borg keeps its shell integration scripts and files copied out of containers in its runtime folder, $XDG_RUNTIME_DIR/borg-commander, or borg-commander-<uid> in the temporary folder. Only you can open this folder; if one already exists that someone else created, or that other users can enter, Borg skips it and uses a new name. Its TTL file starts with the time until which the folder is in use: every running borg pushes that time a day ahead each hour, so once it has passed, the folder can be deleted.

F9 → Options → Borg’s files… shows every place Borg keeps files, how much each one holds, and where it is:

• Temporary files: shell integration scripts, folder requests from the shell, copies out of containers, remote previews, files unpacked from archives for the viewer and the editor, and the certificates of a capture’s proxy, in the runtime folder.
• Sockets: where agents and mirrors reach running sessions, in /tmp/borg-<uid>-default, or in a /tmp/borg-<uid>- folder named after the runtime folder when $XDG_RUNTIME_DIR is set.
• Caches: folder sizes and name indexes, in the cache folder (see Saved size scans).
• Sessions and history: sessions, shell output, the remote log, search and folder history, collections, paired computers with their keys, and what Borg learned about your drives (drives.json), in the state folder.
• Settings: config.toml and your themes.
• Captures: the traffic captures Borg saved, wherever they are.

Up and Down choose a row, and a short note under the list says what the chosen place holds and how long it stays. Enter opens the place’s folder in the active panel. Esc closes the window.

Borg cleans up after itself 30 seconds after it starts and then every hour. It only removes names it makes itself, and never anything that changed in the last 10 minutes, so a Borg that is still starting up keeps what it made. This is what goes:

• Folders of other Borg versions in the runtime folder, once no Borg runs from them, and either no Borg was running when this one started or nothing in them changed for 3 days.
• Folder requests, half-written files, remote console folders and capture proxy certificates of Borg processes that ended.
• Copies out of containers, remote previews and files unpacked from archives for the viewer and the editor, once they are older than a day.
• Sockets nobody answers on, and socket folders where nothing answers any more.
• Size scans in the format of Borg 0.4 and 0.5, scans the cache no longer lists, and name indexes of folders that are no longer indexed.
• Runtime folders that older Borgs left open to other users, once nothing in them changed for 3 days.

Sessions, history, settings and captures stay until you delete them. The line under the note says how much is left over right now and what the last cleanup removed. F8 removes what is left over after asking. The question lists the folders it comes from and starts on No, so press Y to remove them.

Each capture Borg saves goes on a list of the 1,000 newest. The window shows the ones still on disk under Captures Borg saved, with their size and date, and with keys when a .keylog file of the same name sits beside one. Enter on a capture opens its folder with the cursor on the file, so F8 there deletes it. Captures saved before Borg started keeping this list are not on it.

borg storage prints the same places in the terminal and says what is left over, and borg storage clean removes it.

To build, test, or contribute, see Development.