Go embed

The pkg/kiwi package runs a full KiwiFS server, with its REST API, web UI, search, and versioning, inside your Go process. Use it to ship a knowledge base as part of your own binary, or to mount KiwiFS next to your application’s routes.

Install

Terminal

go get github.com/kiwifs/kiwifs/pkg/kiwi

Quick start

main.go

package main

import (
	"log"

	"github.com/kiwifs/kiwifs/pkg/kiwi"
)

func main() {
	srv, err := kiwi.New("/data/knowledge",
		kiwi.WithSearch("sqlite"),
		kiwi.WithVersioning("git"),
		kiwi.WithAuth("apikey", "my-secret"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer srv.Close()

	log.Println("KiwiFS listening on :3333")
	log.Fatal(srv.ListenAndServe(":3333"))
}

kiwi.New creates the directory if needed and initializes a git repository there when versioning is git. It also watches the directory, so files you edit on disk are committed and indexed.

kiwi.New doesn’t read .kiwi/config.toml. The embedded server uses the options you pass and the defaults below. Features configured only in config.toml, such as vector search or backup sync, aren’t available when embedding.

Options

WithSearch(engine string)

Search engine: "sqlite" (default) for full-text search with BM25 ranking, or "grep" for index-free substring matching.

WithVersioning(strategy string)

Versioning strategy: "git" (default), "cow" for copy-on-write snapshots, or "none".

WithAuth(authType, apiKey string)

Authentication. Use "apikey" with a key to require Authorization: Bearer <key> on API requests. The default is "none".

WithCORSOrigins(origins ...string)

Origins allowed to call the API from a browser, such as "https://app.example.com".

Server methods

Handler() http.Handler

Returns the HTTP handler for the REST API and web UI. Use it to serve KiwiFS from your own http.Server or router. The embedded server doesn’t expose the /mcp endpoint that kiwifs serve adds.

Pipeline() *pipeline.Pipeline

Returns the write pipeline for reading and writing pages from Go. See Read and write pages from Go.

ListenAndServe(addr string) error

Serves Handler() on addr with http.ListenAndServe. It blocks until the listener fails.

Shutdown(ctx context.Context) error

Stops KiwiFS’s background schedulers. It doesn’t stop a listener started with ListenAndServe. For graceful shutdown, run your own http.Server as shown below.

Close() error

Stops the file watcher and releases search indexes, vector stores, and git resources. Call it once before your program exits.

Mount next to your own routes

The web UI loads its assets from absolute paths, so mount KiwiFS at the root and put your own routes on paths it doesn’t use. KiwiFS serves its API under /api/kiwi/.

main.go

package main

import (
	"log"
	"net/http"

	"github.com/kiwifs/kiwifs/pkg/kiwi"
)

func main() {
	kb, err := kiwi.New("/data/knowledge")
	if err != nil {
		log.Fatal(err)
	}
	defer kb.Close()

	mux := http.NewServeMux()
	mux.Handle("/", kb.Handler())
	mux.HandleFunc("/app/ping", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("pong"))
	})

	log.Fatal(http.ListenAndServe(":8080", mux))
}

If you only need the API, you can mount it under a prefix with http.StripPrefix. The web UI won’t work under a prefix.

Read and write pages from Go

Pipeline() gives you the same write path the REST API uses. Every write is committed to git, indexed for search, and broadcast to connected clients.

ctx := context.Background()
pipe := srv.Pipeline()

// Create or replace a page. The last argument is the actor recorded in the commit.
res, err := pipe.Write(ctx, "concepts/auth.md", []byte("---\ntitle: Authentication\nstatus: draft\n---\n\n# Authentication\n"), "my-app")
if err != nil {
	log.Fatal(err)
}
log.Println("ETag:", res.ETag)

// Merge frontmatter fields. Pass the ETag to fail on concurrent edits, or "" to skip the check.
_, err = pipe.PatchFrontmatter(ctx, "concepts/auth.md", map[string]any{"status": "published"}, res.ETag, "my-app")

// Read a page and list a folder through the underlying storage.
content, err := pipe.Store.Read(ctx, "concepts/auth.md")
log.Println(string(content))

entries, err := pipe.Store.List(ctx, "concepts")
for _, e := range entries {
	log.Println(e.Path, e.IsDir)
}

// Delete a page.
err = pipe.Delete(ctx, "concepts/auth.md", "my-app")

Write through pipe.Write, pipe.PatchFrontmatter, pipe.Append, pipe.Rename, and pipe.Delete. Writing through pipe.Store directly skips the commit, the index update, and the event broadcast.

Graceful shutdown

Serve Handler() from an http.Server you control, shut that down first, then close KiwiFS.

main.go

package main

import (
	"context"
	"errors"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/kiwifs/kiwifs/pkg/kiwi"
)

func main() {
	kb, err := kiwi.New("/data/knowledge")
	if err != nil {
		log.Fatal(err)
	}

	httpSrv := &http.Server{Addr: ":3333", Handler: kb.Handler()}
	go func() {
		if err := httpSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			log.Fatal(err)
		}
	}()

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	<-ctx.Done()

	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := httpSrv.Shutdown(shutdownCtx); err != nil {
		log.Printf("shutdown: %v", err)
	}
	if err := kb.Close(); err != nil {
		log.Printf("close: %v", err)
	}
}

Always call Close() before exiting. Skipping it can leave pending commits unflushed and search indexes in an inconsistent state, which kiwifs reindex can repair.

REST API

The endpoints Handler() serves.

Files as truth

Why every write goes through the pipeline.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Install

Quick start

Options

Server methods

Mount next to your own routes

Read and write pages from Go

Graceful shutdown

REST API

Files as truth

​Install

​Quick start

​Options

​Server methods

​Mount next to your own routes

​Read and write pages from Go

​Graceful shutdown

​Related

REST API

Files as truth

Install

Quick start

Options

Server methods

Mount next to your own routes

Read and write pages from Go

Graceful shutdown

Related