### # # ### #### ##### # # # # # # # # ## # # # # # ### # # # # # # # # ### ### ### #### #####
Get FoldDB running on your machine in minutes. No developer tools required — just install, launch, and start organizing your data with AI.
----------------------------------------------------------------------------------------------------------------------------------------
macOS APP
Download the .dmg from GitHub releases. Open the file and drag FoldDB to your Applications folder.
github.com/shiba4life/fold_db/releases
Available for Apple Silicon and Intel Macs
HOMEBREW
brew install shiba4life/tap/folddb
Installs folddb and folddb_server binaries
CURL INSTALL SCRIPT
curl -fsSL https://raw.githubusercontent.com/shiba4life/fold_db/master/install.sh | sh
Auto-detects macOS (Apple Silicon / Intel) and Linux x86_64
BUILD FROM SOURCE
Need full control? Clone the repo and build with Cargo.
See the Developer Guide for build instructions.
START THE SERVER
folddb_server
Then open your browser to:
http://localhost:9001
The FoldDB web UI loads automatically. No additional setup needed — the server is zero-config.
If you installed the macOS .dmg app, just open FoldDB from your Applications folder. The UI opens automatically.
The first time you open FoldDB, the onboarding wizard walks you through configuration.
STEP 1 — WELCOME
Overview of what FoldDB does and how it organizes your data with AI.
STEP 2 — CONFIGURE AI
Choose your AI provider:
OpenRouter — Cloud-based AI. Sign up at openrouter.ai and paste your API key.
Ollama — Run AI locally on your machine. Install from ollama.com, then select a model.
AI powers schema detection, keyword extraction, and natural language queries.
STEP 3 — STORAGE
Choose where your data lives:
Local — Data stored on your machine (default). Fast, private, no cloud needed.
Cloud — AWS-backed storage with client-side encryption. Data is encrypted before leaving your device.
STEP 4 — DONE
Configuration saved. You're ready to start using FoldDB.
You can change these settings anytime via the gear icon in the top-right corner of the UI.
INGEST DATA
Upload files or paste JSON directly into FoldDB. AI automatically detects the structure, creates a schema, and extracts searchable keywords.
Supports JSON, CSV, text files, and more
SEARCH
Use the AI Query tab to search your data with natural language. Ask questions like "show me recent purchases" or "find emails from last week."
AI understands context and returns relevant results
BROWSE
The Data Browser tab shows all your stored data organized by schema. Inspect individual records, view fields, and see data history.
Everything is organized automatically by schema
SMART FOLDERS
Point FoldDB at a directory on your machine. It scans for personal data files, processes them with AI, and ingests everything automatically.
Great for importing documents, exports, and archives
UI TAB WHAT IT DOES ───────────────────────────────────────────────────────────────── Data Browser Browse all stored data by schema AI Query Natural language search across your data Ingest Upload files or paste JSON to ingest Smart Folders Scan and auto-ingest directories Schemas View and manage data schemas Settings Configure AI provider, storage, and keys
CLI COMMANDS for power users
COMMAND WHAT IT DOES ───────────────────────────────────────────────────────────────── folddb_server Start the server (UI at :9001) folddb --help Show all CLI commands folddb status -p Check node health folddb ingest run data.json Ingest a JSON file folddb query ai "your question" Natural language query folddb schema list -p List all schemas
See the Developer Guide CLI Reference for the full command list.
AI NOT WORKING
Check your API key in Settings (gear icon). Make sure you've configured either OpenRouter or Ollama. For OpenRouter, verify your key at openrouter.ai/keys. For Ollama, ensure it's running locally.
PORT ALREADY IN USE
Another instance of FoldDB (or another application) is using port 9001. Stop the other process first:
lsof -i :9001 # Find what's using the port kill <PID> # Stop it
PERMISSION DENIED (macOS)
macOS may block apps from unidentified developers. Go to System Settings → Privacy & Security and click "Open Anyway" next to the FoldDB warning.
DATA NOT APPEARING
After ingesting data, it may take a moment for AI to process schemas and keywords. Check the progress indicator in the UI. If ingestion fails, verify your AI provider is configured and responding.
----------------------------------------------------------------------------------------------------------------------------------------
folddb v0.1.0 Open source. Data sovereignty for everyone.
PROJECT GitHub GOAL.md
LINKS Schema Registry Developer Guide
© 2025 Fold DB — Built in the open