Ghostty Admin & Architecture Guide

This guide is for administrators, packagers, distributors, and developers who need to build, deploy, integrate, secure, or understand the internals of Ghostty. It assumes familiarity with the end-user features documented in the companion User Guide.

Ghostty is a cross-platform terminal emulator written in Zig with native platform frontends (AppKit/SwiftUI on macOS, GTK4 + libadwaita on Linux), GPU-accelerated rendering (Metal/OpenGL), and a reusable terminal-engine library (libghostty-vt) exposed to C, C++, Swift, Zig, and WebAssembly.

1. Executive Summary

The codebase at the documented commit is large (~5,400 files, ~8.5 MB of source across src/, macos/, pkg/, example/, and build tooling). The terminal emulation core (src/terminal/) alone is the single largest subsystem.

Note

Ghostty draws a clean compile-time boundary between core logic (Zig, platform-agnostic) and platform runtimes (apprt). Each build selects exactly one application runtime, one renderer, and one font backend at compile time, so there is no runtime plugin system to manage.

2. Architecture Overview

2.1 High-level component map

                         ┌─────────────────────────────────────────┐
                         │            Application Runtime            │
                         │   (apprt: GTK4/libadwaita | AppKit/Swift) │
                         │   windows, tabs, splits, input, clipboard │
                         └───────────────┬───────────────────────────┘
                                         │ owns
                                ┌────────▼─────────┐
                                │   Core Surface    │  src/Surface.zig
                                │  (one terminal)   │  src/App.zig
                                └───┬──────────┬────┘
                  drives           │          │           drives
            ┌────────────────────▼──┐    ┌───▼─────────────────────┐
            │     Render Thread       │    │       IO Thread         │
            │  src/renderer/*         │    │     src/termio/*        │
            │  Metal | OpenGL | WebGL │    │  PTY + subprocess +     │
            │  GPU draw of the grid   │    │  VT stream handler      │
            └───────────┬─────────────┘    └───────────┬─────────────┘
                        │ reads                          │ writes
                        │                  ┌─────────────▼──────────────┐
                        └─────────────────►│   Terminal Engine (VT)     │
                                           │   src/terminal/*           │
                                           │   parser, screen/page,     │
                                           │   modes, OSC/CSI/DCS,      │
                                           │   Kitty graphics/keyboard  │
                                           └────────────┬───────────────┘
                                                        │ uses
                  ┌─────────────────────────────────────┼───────────────────────┐
            ┌─────▼──────┐  ┌──────────────┐  ┌─────────▼────────┐  ┌────────────▼──┐
            │   Fonts     │  │   Config     │  │     Input        │  │   OS / utils  │
            │ src/font/*  │  │ src/config/* │  │  src/input/*     │  │ src/os/*      │
            │ discovery,  │  │ ~200 opts,   │  │ keybinds, kitty  │  │ unicode, simd │
            │ shaping,    │  │ themes, CLI  │  │ keyboard, mouse  │  │ crash, pty    │
            │ sprites     │  │ flags        │  │ encoding         │  │               │
            └─────────────┘  └──────────────┘  └──────────────────┘  └───────────────┘

2.2 The compile-time runtime selection

Three major subsystems are chosen at compile time via src/build_config.zig, which reads build options into comptime constants:

// src/apprt.zig
pub const runtime = switch (build_config.artifact) {
    .exe => switch (build_config.app_runtime) {
        .none => none,   // embedded library (used by the macOS Swift app)
        .gtk  => gtk,    // GTK4 + libadwaita (Linux)
    },
    .lib => embedded,
    .wasm_module => browser,
};

// src/renderer.zig
pub const Renderer = switch (build_config.renderer) {
    .metal  => GenericRenderer(Metal),
    .opengl => GenericRenderer(OpenGL),
    .webgl  => WebGL,
};

Important

On macOS, the user-facing Ghostty.app is a Swift/AppKit application that embeds the Ghostty Zig core as a library (the embedded apprt). On Linux, the ghostty binary is a single Zig executable using the GTK apprt. This is why macOS and Linux have different feature sets and platform-specific options.

2.3 Threading model

Ghostty is heavily multi-threaded for low latency and high throughput:

• GUI / main thread — owned by the app runtime (GTK main loop or AppKit run loop). Handles window management, input events, and dispatches to surfaces.
• IO thread (src/termio/Thread.zig) — one per surface. Reads/writes the PTY, runs the VT stream handler, and updates the terminal screen state.
• Render thread (src/renderer/Thread.zig) — one per surface. Reads the terminal screen state and issues GPU draw calls.

Cross-thread communication uses mailboxes (message queues) rather than shared mutable state where possible. The async event loop is provided by libxev, configurable via async-backend (io_uring/epoll on Linux, kqueue on macOS).

2.4 Source tree map

3. The Configuration System

3.1 Design

The entire configuration surface is a single Zig struct: src/config/Config.zig. Each field maps directly to both a config-file key and a CLI flag (hence the heavy use of @"hyphenated-name" field syntax). Field doc comments are written in Pandoc Markdown and are the source of truth for generated documentation and the +show-config --docs output.

/// Font size in points...
@"font-size": f32 = switch (builtin.os.tag) {
    .macos => 13,
    else => 12,
},

Supporting modules in src/config/:

3.2 Load order and precedence

1. Default values (struct field defaults).
2. The default config file ($XDG_CONFIG_HOME/ghostty/config) unless config-default-files = false is passed on the CLI.
3. config-file includes, applied after the file that references them.
4. CLI arguments (highest precedence; also auto-clear repeatable lists).

3.3 Backwards compatibility

Config.zig declares a compatibility table that renames or remaps deprecated options so old configs keep working, e.g.:

• background-blur-radius → background-blur (1.1)
• adw-toolbar-style → gtk-toolbar-style (1.2)
• bold-is-bright → bold-color = bright (1.2)
• cursor-invert-fg-bg → cell-foreground/cell-background color values (1.2)

Tip

When packaging or writing migration tooling, the compatibility map in Config.zig is the authoritative list of renamed/removed options per version.

3.4 Operational validation

ghostty +validate-config --config-file=/etc/ghostty/config
ghostty +show-config --default --docs        # full effective config + docs
ghostty +explain-config <key>

These are the tools to use in CI or post-deploy smoke tests to confirm a managed configuration is valid.

4. Building from Source

4.1 Toolchain

Ghostty builds with the Zig build system. The required Zig version is pinned in build.zig.zon as minimum_zig_version, and build.zig enforces it at comptime:

comptime { buildpkg.requireZig(minimum_zig_version); }

Warning

You must use the exact pinned Zig version (or newer where the build allows). Mismatched Zig versions are the most common build failure for packagers.

4.2 Common build commands

# Standard optimized build
zig build -Doptimize=ReleaseFast

# Run directly
zig build run

# Run the test suite
zig build test

# Build the dist tarball and validate it
zig build dist
zig build distcheck

Build output lands in zig-out/, including:
  zig-out/bin/ghostty        the executable (GTK/Linux)
  zig-out/share/             terminfo, themes, shell integration, man pages

4.3 Key build options and artifacts

build.zig (via src/build/Config.zig) exposes many -D options. Notable artifacts it can produce:

Build-time configuration (src/build_config.zig) determines app_runtime, renderer, font_backend, i18n, release channel, and the version string (from a VERSION file if present in a tarball, else build.zig.zon).

4.4 The macOS app

The macOS application is built from the Xcode project in macos/ (Ghostty.xcodeproj). It links the Ghostty core compiled as a library (GhosttyKit/ghostty-internal) and provides the AppKit/SwiftUI UI, App Intents, AppleScript dictionary, Services, Quick Terminal, and custom icon system.

Note

Building the macOS app requires macOS with Xcode (for xcodebuild and the xcframework step). The Linux GTK build does not require any of the macos/ tree.

5. Dependencies

Ghostty vendors its native dependencies and pins them by hash in build.zig.zon (mirrored as build.zig.zon.json). Most are fetched from deps.files.ghostty.org for reproducibility. The pkg/ directory contains the Zig build wrappers for the C libraries.

5.1 Core libraries

5.2 Graphics / rendering

5.3 Platform integration

5.4 Crash reporting & fonts

Important

Because dependencies are content-addressed (sha256) in build.zig.zon, downstream packagers can vendor or mirror them deterministically. Air-gapped builds need a local mirror of deps.files.ghostty.org artifacts.

6. Deployment and Packaging

6.1 What gets installed

A complete install consists of the executable plus a share/ resources tree:

bin/ghostty
share/ghostty/themes/          built-in color themes
share/ghostty/shell-integration/   bash, zsh, fish, elvish, nushell scripts
share/terminfo/                xterm-ghostty terminfo
share/man/                     man pages (if docs emitted)
share/locale/                  translations (if i18n enabled)
share/applications/            .desktop file (Linux)

Resources are produced by the GhosttyResources build step. The terminfo (xterm-ghostty) is important — without it, remote/legacy programs may misbehave.

6.2 Linux packaging

Note

The GTK class/app-ID is com.mitchellh.ghostty. Changing it breaks .desktop launching, DBus activation, and systemd user services that expect the default name. Keep it consistent across the desktop file, DBus, and the binary.

6.3 macOS distribution and auto-update

The macOS app is signed and distributed as Ghostty.app with Sparkle-based auto-update. Update behavior is governed by the auto-update and auto-update-channel options:

• auto-update: off / check / download (unset defers to Sparkle defaults).
• auto-update-channel: stable or tip (pre-release). Requires a full restart.

Linux has no built-in updater; updates flow through package managers.

6.4 Single-instance and process isolation (Linux)

gtk-single-instance = detect    # detect | true | false
linux-cgroup = single-instance  # never | always | single-instance
linux-cgroup-memory-limit = 2147483648
linux-cgroup-processes-limit = 512
linux-cgroup-hard-fail = false

When linux-cgroup is active, each surface (tab/split/window) is placed in a transient systemd scope so per-surface resource limits and OOM isolation apply. This requires systemd; by default a failure to create the scope is non-fatal unless linux-cgroup-hard-fail = true.

Tip

For fleet/managed deployments where one runaway shell shouldn't take down the whole terminal, enable cgroup isolation and pair it with systemd-oom.

7. Security

Ghostty implements several defenses against classic terminal-emulator attack classes. Administrators deploying managed configs should understand each.

7.1 Clipboard access (OSC 52)

clipboard-read = ask      # ask | allow | deny
clipboard-write = allow   # ask | allow | deny

Programs can read/write the system clipboard via OSC 52. Reads prompt by default; writes are allowed by default. In hostile environments, set clipboard-read = deny.

7.2 Paste protection

clipboard-paste-protection = true
clipboard-paste-bracketed-safe = true

Pastes containing newlines or control characters are flagged to prevent "paste-injection" attacks where pasted text auto-executes commands. Keep this on.

7.3 Title reporting

title-report = false   # default

The CSI 21 t sequence lets programs query the terminal title. This is disabled by default because a malicious title plus minor user interaction can lead to information disclosure or, in the worst case, command execution. Leave it off unless required.

7.4 Secure Input (macOS)

macos-auto-secure-input = true
macos-secure-input-indication = true

Ghostty can auto-enable macOS "Secure Input" at detected password prompts, preventing other applications from reading keystrokes. Note detection is heuristic and does not work over SSH.

7.5 Automation surfaces (macOS)

macos-applescript = true
macos-shortcuts = ask    # ask | allow | deny

Ghostty exposes an AppleScript dictionary and macOS Shortcuts actions that can create terminals, send text, and invoke any keybind action. These are powerful and can be abused by a malicious script — macos-shortcuts gates Shortcuts access (prompting by default), and macos-applescript = false disables AppleScript entirely.

7.6 Theme and shader trust

• Theme files can set any option, not just colors (but not theme/ config-file). Only ship/allow themes from trusted sources; the bundled themes are audited.
• Custom shaders run on the GPU and can be passed arbitrary GLSL. A bad shader can blank the window. Validate shaders before deploying.

7.7 Resource limits

scrollback-limit (per-surface, in memory) and image-storage-limit (Kitty images per screen, default 320 MB; 0 disables image protocols) bound memory. Background images live in VRAM per terminal. On Linux, cgroup limits (§6.4) cap per-surface memory/process counts.

7.8 Crash reporting

Crash handling uses Sentry/Breakpad to capture minidumps. Reports are managed locally via ghostty +crash-report. Administrators concerned about telemetry should review the crash subsystem (src/crash/) and Sentry configuration before deployment.

Caution

The crash keybind action (and command-palette entry) deliberately crashes Ghostty to test crash handling. Do not expose it in managed configs for general users — it causes data loss in the affected surface.

8. Operations

8.1 Inspecting a running install

ghostty +version            # version, build config, library versions
ghostty +show-config        # effective non-default config
ghostty +list-keybinds      # active keybindings
ghostty +crash-report       # list captured crash reports

8.2 Logs and debugging

8.3 IPC control

A running Ghostty can be controlled out-of-band:

ghostty +new-window
ghostty +toggle-quick-terminal

These use IPC (DBus on GTK) to message the running instance — useful for global shortcuts and scripting. On macOS, App Intents / Shortcuts / AppleScript provide equivalent automation.

8.4 Managed configuration

For fleet deployments:

• Ship a base config and use config-file includes for layering.
• Validate with ghostty +validate-config in CI/post-deploy.
• Remember CLI args override file config and auto-clear repeatable lists, which is handy for one-off overrides (ghostty --theme=...).

9. The Terminal Engine and libghostty-vt

9.1 The engine

src/terminal/ is the heart of Ghostty: a from-scratch VT (DEC/ANSI/xterm) emulator. It includes the escape-sequence parser, the screen/page memory model (a paged, scrollback-aware grid), terminal modes, OSC/CSI/DCS/APC handlers, the Kitty graphics protocol, terminal search, and tmux control-mode support (src/terminal/tmux/). It is the largest subsystem and is exercised by extensive fuzzing corpora under test/fuzz-libghostty/.

9.2 libghostty-vt

A standout architectural feature: the VT engine is shipped as a standalone, embeddable library, libghostty-vt, with a stable C API (include/ghostty/vt.h, implemented by src/terminal/c/ and src/lib_vt.zig). The build produces shared, static, WASM, and Apple xcframework variants.

The example/ directory demonstrates consuming it from many languages:

Tip

If you need a correct, well-tested terminal parser/state machine for your own application (a multiplexer, a recording tool, a web terminal), libghostty-vt lets you reuse Ghostty's engine without the GUI. Build it with the libghostty-vt build steps and link against the generated header.

9.3 Rendering pipeline

The renderer (src/renderer/) consumes terminal screen state on a dedicated thread and draws the cell grid via a backend (Metal.zig, OpenGL.zig, or WebGL.zig) wrapped by a GenericRenderer. It handles cursor styling, custom shaders (shadertoy.zig, compiled via glslang/spirv-cross), background images, and overlays (resize/size reports). VSync is configurable on macOS (window-vsync).

9.4 Fonts

src/font/ handles discovery (CoreText on macOS, fontconfig on Linux), shaping (CoreText or HarfBuzz), fallback chains, variable fonts, font features, and a sprite generator for box-drawing, Powerline, and Nerd Font glyphs (with codegen from nerd_font_codegen.py). Metric adjustments (adjust-*) are applied here.

10. Code Quality and Conventions

11. Potential Improvements & Known Constraints

These are drawn from in-code comments (TODO, BUG, WARNING), community issues, and architectural observations.

11.1 From the code

• Background images use VRAM per-terminal and are duplicated across splits; a noted future improvement is sharing image textures across terminals (background-image doc comment).
• link is not currently settable — the doc comment for link notes "This can't currently be set!", so custom link patterns aren't yet user-configurable (only the default URL matcher via link-url).
• GTK window sizing ignores decorations — window-width/window-height don't account for window decorations on GTK, so grid dimensions can be off unless decorations are disabled (documented BUG).
• Unlimited scrollback is not yet supported — scrollback-limit is always bounded; scrollback is fully in-memory.
• PDF/printing, RTL, and tmux control mode are partially supported or in-progress (see community issues below).

11.2 From community issues

The fetched issues highlight active work areas:

11.3 Operational recommendations

• [ ] Mirror deps.files.ghostty.org artifacts for reproducible/air-gapped builds.
• [ ] Pin and track the required Zig version per release.
• [ ] In managed environments, audit any non-bundled themes (they can set any option).
• [ ] Validate distributed configs in CI with +validate-config.
• [ ] Enable Linux cgroup isolation for multi-tenant or resource-constrained hosts.
• [ ] Review the crash/Sentry subsystem before enabling crash reporting in privacy-sensitive deployments.
• [ ] Ensure the xterm-ghostty terminfo is installed (or rely on the SSH terminfo features) to avoid remote-program breakage.

12. Quick Reference

Identity: app ID com.mitchellh.ghostty · TERM=xterm-ghostty

Build:

zig build -Doptimize=ReleaseFast    # build (requires pinned Zig)
zig build test                      # tests
zig build dist && zig build distcheck

Artifacts: zig-out/bin/ghostty, zig-out/share/ (themes, terminfo, shell integration, man pages), libghostty-vt (shared/static/wasm/xcframework).

Operate:

ghostty +version           # version + build config
ghostty +show-config       # effective config
ghostty +validate-config   # validate
ghostty +crash-report      # crash reports
ghostty +new-window        # IPC to running instance
GTK_DEBUG=interactive ghostty   # GTK inspector (Linux)

Architecture at a glance: Zig core + comptime-selected apprt (GTK / embedded macOS Swift / browser WASM) + comptime-selected renderer (Metal/OpenGL/WebGL). Multi-threaded: GUI + per-surface IO + per-surface render. VT engine reusable as libghostty-vt.

Security defaults to verify: clipboard-read=ask, clipboard-write=allow, clipboard-paste-protection=true, title-report=false, macos-auto-secure-input=true, macos-shortcuts=ask.