README
¶
Filegate
Filegate is a Linux file gateway for applications that need REST, typed SDK, and optional path-style S3 access to normal filesystem storage.
Files remain ordinary files on configured mounts. Stable IDs live in the
user.filegate.id xattr, while a rebuildable Pebble index accelerates listings,
path lookup, uploads, and metadata reads.
Capabilities
- REST API with stable path and node-ID addressing
- resumable and direct browser uploads
- streaming file and directory downloads
- TypeScript and Go clients
- optional path-style S3 listener with scoped access keys
- per-file version history with probed reflink or byte-copy behavior
- polling or btrfs-based external-change detection
- separate operator Admin app
Production boundaries
- Linux-only, single-node, and single-tenant
- one full-authority REST bearer token; narrower scopes exist only for S3 keys
- exactly one daemon per runtime store, index, and writable mount set
- TLS and REST rate limiting belong at the reverse proxy or private network
- user xattrs are required and must be preserved by backup tooling
Read the Security model and Operations guide before deploying.
Install
Install a release package and run Filegate through systemd. Replace amd64
with arm64 on ARM hosts.
curl -fL -o /tmp/filegate.deb \
https://github.com/k2b-dev/filegate/releases/latest/download/filegate_linux_amd64.deb
sudo dpkg -i /tmp/filegate.deb
sudo systemctl enable --now filegate
The first start generates and prints a REST token when none is configured. The
token and applied runtime configuration are persisted under
/var/lib/filegate/config.
Verify liveness, then follow the authenticated readiness procedure in the installation guide:
curl -fsS http://127.0.0.1:8080/health
Documentation
The canonical documentation is the Fibel site at filegate.dev/docs.
- Getting started
- Installation
- Configuration
- HTTP API
- TypeScript SDK
- Go SDK
- S3 compatibility
- Admin UI
- Reference
- Development architecture
The site also exposes searchable pages, raw Markdown, and llms.txt. Its source
lives in docs-site/docs/en.
Development
go test ./...
go vet ./...
staticcheck ./...
Run the documentation site:
cd docs-site
bun install --frozen-lockfile
bun run typecheck
bun run dev
Agent skills
bunx skills add k2b-dev/filegate
- Integration skill:
skills/filegate/SKILL.md - Contributor skill:
skills/filegate-dev/SKILL.md
Directories
¶
| Path | Synopsis |
|---|---|
|
adapter
|
|
|
http
Package httpadapter provides the HTTP transport layer for the Filegate API.
|
Package httpadapter provides the HTTP transport layer for the Filegate API. |
|
s3
Package s3 implements an S3-compatible HTTP frontend for filegate.
|
Package s3 implements an S3-compatible HTTP frontend for filegate. |
|
api
|
|
|
v1
Package v1 defines the versioned API request and response types for Filegate.
|
Package v1 defines the versioned API request and response types for Filegate. |
|
Package cli implements the Filegate command-line interface using Cobra and Viper.
|
Package cli implements the Filegate command-line interface using Cobra and Viper. |
|
cmd
|
|
|
filegate
command
Package main is the entry point for the Filegate server binary.
|
Package main is the entry point for the Filegate server binary. |
|
filegate-bench
command
|
|
|
Package domain provides the core business logic for the Filegate filesystem gateway.
|
Package domain provides the core business logic for the Filegate filesystem gateway. |
|
infra
|
|
|
activity
Package activity provides the in-process activity log used by the admin UI and lightweight operator introspection.
|
Package activity provides the in-process activity log used by the admin UI and lightweight operator introspection. |
|
cache
Package cache provides a generic LRU cache wrapper used for path-to-ID and ID-to-path lookups in the domain service layer.
|
Package cache provides a generic LRU cache wrapper used for path-to-ID and ID-to-path lookups in the domain service layer. |
|
detect
Package detect provides filesystem change detection backends for Filegate.
|
Package detect provides filesystem change detection backends for Filegate. |
|
eventbus
Package eventbus implements the domain.EventBus interface with an in-memory publish/subscribe mechanism.
|
Package eventbus implements the domain.EventBus interface with an in-memory publish/subscribe mechanism. |
|
fgbin
Package fgbin defines the binary codec for Filegate index records.
|
Package fgbin defines the binary codec for Filegate index records. |
|
filesystem
Package filesystem implements the domain.Store interface using OS filesystem operations.
|
Package filesystem implements the domain.Store interface using OS filesystem operations. |
|
jobs
Package jobs provides a bounded worker pool with keyed job deduplication.
|
Package jobs provides a bounded worker pool with keyed job deduplication. |
|
metrics
Package metrics provides the Prometheus instrumentation surface for filegate: an HTTP RED middleware shared by the REST + S3 adapters, a set of counters the background loops feed, a scrape-time domain collector, and the /metrics HTTP handler.
|
Package metrics provides the Prometheus instrumentation surface for filegate: an HTTP RED middleware shared by the REST + S3 adapters, a set of counters the background loops feed, a scrape-time domain collector, and the /metrics HTTP handler. |
|
pebble
Package pebble implements the domain.Index interface using CockroachDB's Pebble embedded key-value store.
|
Package pebble implements the domain.Index interface using CockroachDB's Pebble embedded key-value store. |
|
runtimecfg
Package runtimecfg persists the last-applied configuration manifest and runtime resources such as S3 access keys.
|
Package runtimecfg persists the last-applied configuration manifest and runtime resources such as S3 access keys. |
|
sdk
|
|
|
filegate
Package filegate provides a stateless Go client SDK for the Filegate HTTP API.
|
Package filegate provides a stateless Go client SDK for the Filegate HTTP API. |
|
filegate/directuploads
Package directuploads contains helpers for upload-session direct tokens.
|
Package directuploads contains helpers for upload-session direct tokens. |
|
filegate/relay
Package relay provides HTTP passthrough helpers for backends that proxy Filegate responses to their own clients without re-buffering bodies.
|
Package relay provides HTTP passthrough helpers for backends that proxy Filegate responses to their own clients without re-buffering bodies. |
|
filegate/segments
Package segments contains pure helpers for resumable uploads.
|
Package segments contains pure helpers for resumable uploads. |
|
filegate/uploadtree
Package uploadtree uploads whole folders through Filegate upload sessions.
|
Package uploadtree uploads whole folders through Filegate upload sessions. |
Click to show internal directories.
Click to hide internal directories.