Customization

Webshell Configuration Guide

Per-user web terminal preferences are stored in ~/.config/webshell/.

---

Directory Structure

~/.config/webshell/
├── config.json      # Theme, font size, and cursor settings
└── font.woff2       # (Optional) Local custom font file (.woff2, .ttf, or .otf)

---

config.json Options

Key	Type	Default	Description
fontFamily	String	'JetBrains Mono', monospace	Font family stack
fontSize	Number	15	Font size in pixels
cursorStyle	String	"block"	Cursor shape ("block", "underline", or "bar")
cursorBlink	Boolean	true	Enable or disable cursor blinking
theme	Object	See below	Color palette overrides

---

Theme Options (theme object)

Key	Description
background	Terminal background color (e.g. "#000000")
foreground	Default text color (e.g. "#e0e0e0")
cursor	Cursor color (e.g. "#ffffff")
black – white	Standard 8 ANSI colors
brightBlack – brightWhite	High-intensity 8 ANSI colors

---

Example ~/.config/webshell/config.json

{
  "fontFamily": "'JetBrains Mono', 'Fira Code', monospace",
  "fontSize": 15,
  "cursorStyle": "block",
  "cursorBlink": true,
  "theme": {
    "background": "#000000",
    "foreground": "#e0e0e0",
    "cursor": "#00ff00",
    "green": "#00ff00",
    "cyan": "#00ffff"
  }
}

---

Using Local Font Files

Location

Place your font file in ~/.config/webshell/ as one of the following:

• font.woff2 (Recommended)
• font.ttf
• font.otf

The webshell will automatically encode and load your font file into the web browser upon login.

Determining Font Family Name from a Font File

fc-scan will return the font family name for you. It is possible to return multiple aliases so you can use the first one to simplify the process.

$ fc-scan GoogleSansCodeNerdFontMono-SemiBoldItalic.ttf --format "%{family}\n" | cut -d, -f1
GoogleSansCode Nerd Font Mono

Use woff2 files instead of ttf or otf

These are normal font files, but compressed so it will be nicer for web use:

# one at a time
for f in *.ttf *.otf; do woff2_compress "$f"; done
# use all those cores!
parallel woff2_compress ::: *.[ot]tf

On 181 of my fonts the size dropped from 381M to 220M.