Folderbase turns an ordinary folder into a structured, versioned workspace that
humans and agents can understand and operate across sessions. Files remain
normal files. A small .folderbase/ directory adds the durable identity,
protocol records, history, and policy needed to treat the folder as a database.
Folderbase is in Beta. The product, documentation, and optional capabilities are still evolving. Compatibility Contract v1 remains the deliberately stable integration boundary; features outside that named contract must be discovered and pinned explicitly.
Folderbase is the open database core beneath Folderbase Cloud, in the same way that PostgreSQL is the open database beneath managed platforms. The core works locally and does not require a Folderbase account.
Start in 60 seconds
From any folder, with Node.js 22.14 or newer:
Initialization is additive. It leaves every existing file at its ordinary path and creates the minimum engine-owned state:
your-folder/
├── .folderbase/
│ └── manifest.json
└── …your existing repositories, documents, media, and data
That folder now has a durable Folderbase ID and a machine-readable contract that Codex, Claude, remote VMs, scripts, and apps can discover locally. It is still a normal folder: existing editors, terminals, Git workflows, and native file tools continue to work.
Install
Use npx for a zero-setup invocation, including inside a remote agent VM:
Install the same native CLI persistently with Homebrew or Cargo:
# or, with Rust 1.96+
Prebuilt macOS and Linux binaries and their closed SHA256SUMS record are
available from GitHub Releases.
Every channel runs the same released Core executable and Compatibility
Contract. The exact tag, registry identities, checksums, and independent
clean-install commands for the prior baseline are recorded in the
v0.6.1 public distribution evidence.
Core 0.7.1 adds exact whole-Version root reconstruction without expanding
Compatibility Contract v1.
Integrate an agent or application
The CLI JSON interface is the universal integration surface. Callers do not
need to link the Rust library or interpret private .folderbase/ internals:
Node.js and TypeScript consumers can use the same executable seam without reimplementing Core process supervision:
import from "@folderbase/sdk";
const folderbase = ;
const contract = await folderbase.;
The SDK is removable, has no runtime dependencies, bundles no native binary,
and never interprets engine-owned .folderbase/ records.
Compatibility Contract v1 freezes portable record meanings, Version IDs, manifest behavior, explicit upgrade behavior, CLI JSON envelopes and exit meanings. Additive fields may appear, so integrations should ignore unknown JSON fields. See the Compatibility Contract and CLI JSON specification.
protocol contract --json also returns a deterministic optional-capability
inventory. This lets an app, agent, or remote VM require an exact stable or
experimental profile without parsing help text. Verify every advertised known
profile from a source release with:
Design principles
- Folders stay folders. Existing repositories, documents, media, PDFs, databases, and other file types keep their ordinary paths and native tools.
- Agents are first-class users. Ordinary files remain directly readable,
while optional
FOLDERBASE.mdcontext and opt-inAGENTS.mdorCLAUDE.mdadapters can provide local entry points without becoming authority. - Structure is guidance, not a cage. Templates initialize useful structure and can expand over time. Reorganization is explicit, previewable, and reversible.
- Local work is complete work. Keep-local workspaces remain fully usable offline. Cloud availability never silently evicts active files.
- Sharing is explicit authority. Folder scopes can be granted to humans or agent sessions; nesting and relationships never imply access.
- Changes preserve evidence. Local versions, resumable content transfer, conflict preservation, and migration rollback protect ongoing work.
What is included
folderbase-core: Rust library for inspection, initialization, validation, templates, migration, local versions, workspace operations, sharing policy, canonical bounded-memory transfer planning/source streaming, canonical Folderbase Version validation/digests/controlled encoding, read-only metadata capture planning, and sync primitivesfolderbase: reference command-line interface@folderbase/sdk: typed Node.js process adapter for CLI JSON and daemon stdio- metadata-first query/index, additive template expansion, scoped Change Sets, exact whole-Version root reconstruction, and root-pinned daemon capability profiles
- versioned JSON Schemas and conformance fixtures
- built-in person, organization, customer, engagement, project, temporary, and custom templates
- an unmanaged, mixed-file project fixture used for end-to-end migration tests
The commercial desktop app, managed sync service, web workspace, and cloud agent runtime live in the separate Folderbase Platform repository.
Trust boundary
.folderbase/ is engine-owned local database state, analogous to .git/.
Local Core treats internally consistent records there as trusted state. It
still fails closed on malformed or partial records, interrupted writes,
ordinary concurrent races, path or inode substitution, unexpected hard links,
and any operation that would overwrite existing workspace content.
Local Core does not claim cryptographic authenticity against a local process
running as the same user that deliberately rewrites every related
.folderbase/ record into one internally consistent forgery. Protecting local
state from that actor would require an OS-protected device key and a larger key
recovery UX, which is intentionally outside the KISS local protocol. Folderbase
Cloud and server-side sharing authority are separate authenticated trust
domains; local metadata possession alone never grants Cloud access.
Nested traversal recognizes only the exact, no-follow
.folderbase/manifest.json regular-file marker as an opaque boundary; it does
not decode the nested bytes through the parent. Markerless .folderbase state
and optional context are inert. Case aliases and symlink or wrong-type marker
shapes gain no authority: read-only analysis may quarantine them as
Unchecked (unchecked on the wire) and omit descendants, while
materialization, mutation, transfer, and restore operations reject them.
Turn a folder into a Folderbase
Inspect first. Inspection reads metadata and boundaries without changing the folder:
Preview the additive initialization:
The JSON plan includes a stable Core-owned plan_digest. To bind approval to
the exact reviewed request, template, protocol writes, boundaries, and visible
destination state, apply with that digest:
After a captured deletion, restore the current Local Head's exact ordinary-file Tombstone without overwriting anything already at that path:
This restores the sealed opaque bytes and executable fidelity under the original Object ID and Object Version, then creates one new full-state Folderbase Version. Directory and symlink Tombstones are not restored by v1.
An independently produced, package-pinned full Version can reconstruct one
absent ordinary root through the advertised stable
folderbase.root-reconstruction@0.1.0 capability:
The request binds one operation ID and the exact package-index SHA-256. Core verifies every opaque object, restores all supported file types without interpreting them, retains restorable Tombstone history, and publishes the destination with no-clobber semantics. Source and destination authorities must be absolute and physically separate. See the root reconstruction capability for the closed package and process contracts.
The CLI asks Core for one plan. Apply carries the opaque digest from that plan;
Core compares it and performs a bounded, metadata-only preflight immediately
before its first write. The digest includes the physical filesystem identity of
the reviewed root, so replacing a folder with a same-path, same-shape folder in
another process is stale. New paths, kind changes, boundary changes, or planned
target collisions also return a typed stale-plan error with no protocol writes.
Content edits to ordinary preserved files do not create approval churn because
Core never writes those files. folderbase init /path/to/project remains
available for direct, single-step initialization.
This is optimistic concurrency, not atomic filesystem isolation. A race after preflight is contained by root-capability traversal, no-follow parent opens, and per-write no-clobber installation; competing bytes are preserved and the operation fails rather than overwriting them.
Native protocol 0.5 initialization leaves the original files in place and creates only the machine-readable manifest by default:
project/
├── .folderbase/
│ └── manifest.json
└── …your existing files
Root FOLDERBASE.md is fully ordinary optional content. Root
.folderbaseignore is optional user-owned capture-policy input: when present
it is bounded, force-captured, and changed through typed policy-aware flows.
Agent adapters are opt-in and are never independent authority.
For a disorganized or multi-boundary folder, use the migration workflow. It analyzes the folder, asks bounded questions, produces a reviewable plan, and does not apply it unless explicitly approved:
Work with files
The workspace interface lists ordinary files while keeping protocol state, repository internals, and reconstructable dependency trees out of agent context:
Text saves use an expected SHA-256 so stale agent sessions cannot silently overwrite newer work:
|
Binary and very large files remain part of the workspace. Agents can inspect
their metadata first; transformations operate with streaming and
content-addressed chunks rather than loading entire files into model context.
Core opens a transfer source by immutable VersionId, never by the mutable
workspace path. The source binds a canonical manifest to that exact
content-addressed blob and emits a verification receipt only after an exact
chunk range has been streamed and checked.
Protocol
- Domain language
- Compatibility Contract v1
- Stable CLI JSON v1
- Protocol specification
- Template protocol
- Reorganization Protocol 0.3
- Proposed Reorganization Plan decision
- Schemas, templates, and conformance vectors
- Accepted canonical streaming-transfer decision
- Accepted bounded full-state Folderbase Version decision
- Proposed metadata-first capture transaction
- Accepted ordinary-folder and optional-narrative decision
- Proposed durable migration transaction module
- Accepted native distribution decision
- Accepted minimal compatibility decision
- Accepted optional-capability discovery decision
Cargo packages remain below 1.0, but the surfaces named by Compatibility Contract v1 are stable. Experimental surfaces may change between minor Cargo versions. Breaking the named portable records, identifiers, CLI JSON fields, exit meanings, or conformance behavior requires a new compatibility contract.
Implement Folderbase in another language
The public fixture suite is the authority—not this Rust implementation. A Go, TypeScript, or other independent implementation can run the same conformance runner against its executable:
The suite checks the stable CLI contract and portable protocol fixtures without using Rust internals. Passing it demonstrates behavioral compatibility with Folderbase Compatibility Contract v1.
Product boundaries
This repository is the Apache-2.0 Folderbase Database Core: the portable protocol, reference engine, CLI, schemas, fixtures, and conformance suite.
The commercial Folderbase App provides the Better Finder experience and the reliable local-to-cloud bridge. Folderbase Cloud hosts, syncs, and shares live Folderbases with scoped permissions for humans and agents. Folderbase Cloud Agents will run agent sessions against ordinary Folderbase workspaces and return reviewable changes. Cloud authority and sync behavior are not invented or implied by local Core records.
Development
See CONTRIBUTING.md and SECURITY.md before submitting changes or reporting a vulnerability.
License
Licensed under the Apache License 2.0.