kittyd

kittyd is a ready-to-use full-stack terminal access package for Go. It integrates the high-performance Ghostty WASM frontend with a powerful Go backend, allowing you to easily add robust web terminal capabilities to any Go application.

Features

• Gin Integration: Built-in support for the Gin web framework via ginmill.
• Standalone Mode: Quickly launch a dedicated terminal server with graceful shutdown and signal handling.
• Embedded Assets: Frontend assets are embedded in the Go binary for zero-configuration deployment.
• Customizable: Flexible configuration for terminal session factories, static assets, and logging.
• Signal Handling: Supports SIGHUP for configuration reload and SIGINT/SIGTERM for graceful shutdown.

Installation

go get github.com/gjchentw/go-kittyd

Usage

1. The Ginmill Way (Recommended)

Integrate kittyd into an existing Gin application as a modular feature.

package main

import (
    "log"
    "github.com/gin-gonic/gin"
    "github.com/ginmills/ginmill"
    "github.com/gjchentw/go-kittyd/pkg/kittyd"
)

func main() {
    r := gin.Default()

    // 1. Create Config (optional, defaults to EchoTerminal if nil)
    cfg := kittyd.Config{
        SessionFactory: func() (kittyd.Terminal, error) {
            // Return your terminal implementation here (e.g., PTY or SSH)
            return kittyd.NewEchoTerminal(), nil
        },
    }

    // 2. Initialize kittyd and get its features
    k := kittyd.New(cfg)
    features := kittyd.Features(k)

    // 3. Mount features using ginmill
    s := &ginmill.Server{Engine: r}
    s.With(features)

    r.Run(":8080")
}

2. Standalone Mode

Launch a dedicated terminal server with built-in signal handling and graceful shutdown.

package main

import (
    "log"
    "github.com/gjchentw/go-kittyd/pkg/kittyd"
)

func main() {
    cfg := kittyd.Config{
        SessionFactory: func() (kittyd.Terminal, error) {
             // Return an OS command terminal (PTY)
             // cmd := exec.Command("bash")
             // return kittyd.NewOSCommandTerminal(cmd)
             return kittyd.NewEchoTerminal(), nil
        },
        OnReload: func() {
            log.Println("Configuration reloaded via SIGHUP")
        },
    }

    // Start server at :8080 with the given config
    if err := kittyd.Start(":8080", cfg); err != nil {
        log.Fatalf("Server failed: %v", err)
    }
}

Configuration

The Config struct allows you to customize the server's behavior:

Field	Type	Description	Default
SessionFactory	func() (Terminal, error)	Factory function to create a new terminal session.	NewEchoTerminal()
OnReload	func()	Callback function triggered by SIGHUP signal.	nil
Dist	http.FileSystem	Filesystem for serving frontend assets.	Embedded Ghostty assets
Logger	Logger	Logger interface for server logs.	log.Default()

Development

Prerequisites

• Go 1.23+
• Node.js & npm (for frontend changes)

Running tests

go test -v ./pkg/kittyd/...

License

MIT License. See LICENSE for details.