Skip to main content

​
Quickstart Guide

This guide will walk you through generating your first Ghostty configuration using Ghostty Config. You’ll learn how to customize settings, preview your changes, and export your config for use with Ghostty terminal.

​
Prerequisites

Before you begin, make sure you have:
  • A web browser (Chrome, Firefox, Safari, or Edge)
  • Ghostty terminal installed on your system (optional, but recommended for testing)
You don’t need to install anything to use Ghostty Config - it runs entirely in your browser!

​
Generate Your First Config

1

Visit the Site

Navigate to ghostty.zerebos.com in your web browser.You’ll see the home page with information about recent changes and the project roadmap.
2

Explore the Settings Categories

Use the sidebar navigation to browse different configuration categories:
  • Application: Window titles, startup commands, shell integration
  • Clipboard: Copy/paste behavior and permissions
  • Window: Size, decorations, padding, and visual effects
  • Colors: Themes, palettes, and color customization
  • Fonts: Font families, sizes, and typography settings
  • Keybinds: Keyboard shortcuts and bindings
  • Mouse: Mouse behavior and interactions
  • GTK/Linux/macOS: Platform-specific settings
Start with the Colors and Fonts sections for the most visible customizations!
3

Customize Your Settings

Click on any category to start customizing. For example, let’s customize colors:
  1. Navigate to Colors in the sidebar
  2. Click on Color theme dropdown to browse community themes
  3. Select a theme like “Dracula” or “Solarized Dark”
  4. Watch the preview update in real-time
// Example: The color theme setting in the source code
{
  id: "theme",
  name: "Color theme",
  note: "Any colors selected after setting this will overwrite the theme's colors.",
  type: "theme",
  value: "",
  options: [{name: "Custom", value: ""}]
}
When you select a theme, any individual color changes you make afterward will override the theme’s values.
4

Preview Your Changes

Ghostty Config provides real-time previews for visual settings:
  • Cursor Preview: See your cursor style, color, and opacity
  • Color Palette: View all 256 colors in your palette
  • Base Colors: Preview background, foreground, and selection colors
  • Font Preview: Test different fonts and sizes
  • App Icon Preview: See custom macOS app icons (macOS section)
Try adjusting the background opacity:
  1. Go to Window → Appearance
  2. Find Background opacity
  3. Drag the slider to adjust (0.0 = transparent, 1.0 = opaque)
  4. See the preview update instantly
5

Configure Keybindings (Optional)

Navigate to the Keybinds section to customize keyboard shortcuts:
  1. Click the + button to add a new keybinding
  2. Press your desired key combination
  3. Select an action from the dropdown
  4. The binding is validated to prevent conflicts
Example keybinding format from the source:
// Keybindings are stored as strings in the format "keys=action"
type KeybindString = `${string}=${string}`;

// Examples from the default config:
"super+t=new_tab"
"super+w=close_surface"
"super+c=copy_to_clipboard"
"super+enter=toggle_fullscreen"
6

Export Your Configuration

Once you’re happy with your settings, navigate to Import & Export:Option 1: Copy to Clipboard
  1. Click the Clipboard button under Export
  2. The button will show “Copied!” to confirm
  3. Paste the config into your Ghostty config file
Option 2: Download as File
  1. Click the File… button under Export
  2. A file named config will be downloaded
  3. Move it to your Ghostty config directory
The exported config includes a header and only the settings you changed:
# Config generated by Ghostty Config

font-size = 14
background = #282c34
foreground = #ffffff
cursor-style = block
theme = Dracula
7

Use Your Config with Ghostty

Apply your exported configuration to Ghostty:macOS/Linux:
# Create the config directory if it doesn't exist
mkdir -p ~/.config/ghostty

# Paste your config into the file
nano ~/.config/ghostty/config

# Or move the downloaded file
mv ~/Downloads/config ~/.config/ghostty/config
Reload Ghostty:
  • Press Cmd+Shift+, (macOS) or Super+Shift+Comma (Linux)
  • Or restart Ghostty to see your changes
You can also use the config-file setting to load additional config files for different profiles!

​
Import an Existing Config

If you already have a Ghostty config file, you can import it to continue editing:
1

Navigate to Import & Export

Click on Import & Export in the sidebar.
2

Choose Import Method

From Clipboard:
  1. Copy your existing config file contents
  2. Click the Clipboard button under Import
  3. Your settings will be loaded automatically
From File:
  1. Click the File… button under Import
  2. Select your config file from the file picker
  3. Settings will be parsed and loaded
The import parser supports standard Ghostty config syntax:
// Example from parse.ts - config format parsing
const re = /^\s*([a-z-]+)[\s]*=\s*(.*)\s*$/;

// Supports settings like:
// font-size = 14
// palette = 0=#1d1f21
// keybind = super+t=new_tab
3

Review and Modify

After importing, browse through the settings to verify everything loaded correctly. Make any additional changes you’d like, then export again.

​
Tips for Success

Start Simple: Begin by customizing just colors and fonts. You can always add more advanced settings later.
Use the Preview: The config preview in the Import & Export section shows exactly what will be exported, helping you verify your changes.
Experiment Safely: Since Ghostty Config runs in your browser, you can experiment freely without affecting your actual terminal until you export and apply the config.
Some advanced settings (like custom shaders or font adjustments) can cause issues if misconfigured. Be careful when modifying settings marked as “Advanced” or with warning notes.

​
What’s Next?

Now that you’ve generated your first config, explore more:

Browse Color Themes

Explore hundreds of community themes in the Colors → Color theme dropdown

Try the Font Playground

Experiment with different fonts in the Font Playground section

Customize Keybindings

Set up your perfect keyboard shortcuts in the Keybinds section

Platform Settings

Configure platform-specific options for macOS, Linux, or GTK

​
Need Help?

This tool is in active development. If you encounter bugs or have suggestions, please report them on the GitHub issue tracker.
Useful Resources:

Build docs developers (and LLMs) love

Get started for freeTalk to us