Install

Installation

Install with one command. macOS requires no external dependencies (uses NFS). Linux needs FUSE3.

curl -fsSL https://install.tigerfs.io | sh

Platform notes

PlatformDetails
macOSNFS backend. No external dependencies needed.
LinuxFUSE backend. Install via apt install fuse3 or yum install fuse3.
DockerRequires FUSE device access: --device /dev/fuse --cap-add SYS_ADMIN
CLI reference

CLI reference

CommandDescription
tigerfs mountMount a database to a local directory. See Quick start.
tigerfs unmountUnmount a mounted database.
tigerfs createCreate a new cloud database. tigerfs create tiger:my-db. See Cloud backends.
tigerfs forkFork (clone) a database. tigerfs fork /mnt my-experiment. See Cloud backends.
tigerfs listList all available databases (cloud backends).
tigerfs statusShow status of all active mounts.
tigerfs infoInspect a mount. tigerfs info /mnt or --json for scripting.
tigerfs configShow or modify configuration. tigerfs config show. See Configuration.
tigerfs migrateRun pending database schema migrations. See Upgrading.
tigerfs test-connectionTest connectivity to a database without mounting.
tigerfs versionPrint TigerFS version information.
Quick start

Quick start

Mount a database, explore it, write a file, then unmount.

TigerFS extends each directory with special dot-prefixed directories like .build/, .info/, and .export/ for creating apps, inspecting metadata, and querying data, plus .history/, .log/, .savepoint/, and .undo/ on history-enabled workspaces. Like all dotfiles in Unix, they're hidden by default. Use ls -a to see them.

# Mount a remote database export PGPASSWORD=your-password tigerfs mount postgres://[email protected]/mydb /mnt # List tables ls /mnt/ # Create a markdown app and write a file echo "markdown,history" > /mnt/.build/notes cat > /mnt/notes/hello.md << 'EOF' --- title: Hello World author: alice --- # Hello World EOF # Read it back, search, explore cat /mnt/notes/hello.md grep -l "author: alice" /mnt/notes/*.md ls /mnt/notes/ # Unmount tigerfs unmount /mnt
Cloud backends

Cloud backends

Cloud backends give you credential-free mounting. No connection strings to manage. Authenticate once, then create and mount databases by name.

BackendDescription
Tiger Cloud (CLI)Production PostgreSQL with TimescaleDB
Ghost (CLI)Instant databases for agents

Authenticate and create

# Tiger Cloud tiger auth login tigerfs create tiger:my-project /mnt # Ghost ghost login tigerfs create ghost:my-project /mnt

Fork and inspect

Fork a live database to experiment safely. The fork is a full copy you can modify without affecting the original:

# Fork a mounted database tigerfs fork /mnt my-experiment # Or fork by service ID tigerfs fork tiger:e6ue9697jf my-experiment # Inspect a mount tigerfs info --json /mnt

Mount by service ID

Mount cloud databases directly by their service ID. Set a default backend to skip the prefix:

# Mount by service ID # Set a optional default backend in ~/.config/tigerfs/config.yaml tigerfs mount tiger:e6ue9697jf /mnt # Or mount any existing Postgres database directly tigerfs mount postgres://[email protected]/mydb /mnt
File-first mode

File-first mode

Start with files, get a database for free. Write markdown with frontmatter, organize into directories, build lightweight apps on top of the filesystem.

Every write is an atomic database transaction. No partial saves, no corrupted files. Multiple agents and humans can write to the same directory concurrently.

Creating apps with .build/

The .build/ special directory creates new apps. Write the app type and the table becomes a directory of files:

# Create a markdown app echo "markdown" > /mnt/.build/blog # Create a markdown app with version history echo "markdown,history" > /mnt/.build/notes

Markdown and YAML frontmatter

YAML frontmatter becomes database columns. The body becomes the text column.

cat > /mnt/blog/hello-world.md << 'EOF' --- title: Hello World author: alice tags: [intro] --- # Hello World Welcome to my blog... EOF

Column mapping

SourceColumnType
filename_pathtext (primary key)
frontmatter keyskey nameauto-detected (text, integer, boolean, jsonb)
body (below frontmatter)_bodytext

Subdirectories

Use mkdir to create folders, mv to move files between them. Directory structure is encoded in the _path column:

mkdir /mnt/blog/tutorials mv /mnt/blog/hello-world.md /mnt/blog/tutorials/

History, savepoints & undo

Workspaces can opt into automatic versioning with the history feature. Every write — create, edit, rename, delete — is then captured in an operation log with timestamp and user identity, and exposed through the filesystem. Requires TimescaleDB (included with Tiger Cloud and Ghost). See the file-first overview for the bigger picture.

Add history when creating the workspace:

echo "markdown,history" > /mnt/.build/notes

Browse past versions: .history/

Every snapshot of a file is a timestamped, read-only path. History tracks files across renames via stable row UUIDs and stores versions in compressed TimescaleDB hypertables.

PathDescription
.history/Lists all files that have history
.history/file.md/Lists all versions of a file (timestamped)
.history/file.md/2026-02-24T150000ZA specific past version
.history/file.md/.idStable row UUID (tracks across renames)
# list and read a past version ls /mnt/notes/.history/hello.md/ cat /mnt/notes/.history/hello.md/2026-02-12T013000Z

Browse what happened: .log/

Each operation is recorded with a log_id (UUIDv7), its type, the affected file, and the user. Filter by recency, user, or type, and diff any single edit via its before/current/after virtual files.

PathDescription
.log/.last/N/The N most recent operations
.log/.by/file_id/ID/Operations on one file (stable id)
.log/.by/user_id/USER/Operations by one user
.log/.by/type/TYPE/By type: create, edit, rename, delete, undo
.log/ID/before · /current · /afterVirtual files for diffing one edit
# 10 most recent operations cat /mnt/notes/.log/.last/10/.export/json # diff a specific edit diff -u /mnt/notes/.log/<id>/before /mnt/notes/.log/<id>/current

A note on edit counts. Editors that write atomically — Claude's Write/Edit, vim, VS Code — create a temp file, delete the original, and rename temp into place, so each logical save shows as 2–3 log entries. To reverse a logical edit, anchor at the log entry just before the group and use .undo/to-id/. Look files up by stable file_id (filenames aren't a .log/.by/ index, since a file can be renamed).

Savepoints: .savepoint/

Named bookmarks of a workspace state, created by writing JSON; they survive across sessions and users. Auto-savepoints (--auto-savepoint-interval, default 30m) also record bookmarks at session-boundary inactivity gaps.

echo '{"description":"Before refactoring"}' > /mnt/notes/.savepoint/before-refactor.json

Undo: .undo/

Reverse a single operation, everything since a log entry, or everything since a savepoint, optionally filtered by user. Preview before applying. Undo operations are themselves logged and reversible, so changing your mind is one more .apply.

ActionCommand
Preview undo to savepointcat workspace/.undo/to-savepoint/name/.info/summary
Diff all since savepointdiff -ru workspace/.undo/to-savepoint/name workspace/ -x '.*'
Undo to savepointtouch workspace/.undo/to-savepoint/name/.apply
Undo to a log entrytouch workspace/.undo/to-id/<log_id>/.apply
Undo a single changetouch workspace/.undo/id/<log_id>/.apply
Per-user undotouch workspace/.undo/to-savepoint/name/.by/user_id/X/.apply

Example: building a task queue

Directories + atomic moves = a lightweight task board. No external queue, no API, just the filesystem:

# Set up a task board mkdir /mnt/tasks/todo /mnt/tasks/doing /mnt/tasks/done # Agent claims a task (atomic move) mv /mnt/tasks/todo/fix-auth.md /mnt/tasks/doing/ # Mark complete mv /mnt/tasks/doing/fix-auth.md /mnt/tasks/done/
Data-first mode

Data-first mode

Any tool that reads files can query a database. Agents, scripts, and shell pipelines work without knowing there's a database underneath.

Every path maps to a SQL query. Pipeline queries push filters, ordering, and pagination into the database so only matching rows are transferred. Chained paths compile to one optimized query, not N filesystem calls. The database does the work.

Each table includes special dot-prefixed directories for metadata (.info/), queries (.by/, .filter/, .order/), bulk I/O (.export/, .import/), and schema management (.create/, .modify/). Use ls -a inside any table to discover them.

Backing tables via .tables/

File-first apps are stored in tables in the tigerfs schema, with a view in the user schema exposing them as .md or .txt files. The .tables/ directory at the root of a mount gives you data-first access to those backing tables with full pipeline support.

# List backing tables ls /mnt/.tables/ notes/ blog/ snippets/ # Inspect a backing table cat /mnt/.tables/notes/.info/schema cat /mnt/.tables/notes/.info/count # Query rows by column using pipeline segments cat /mnt/.tables/notes/.by/author/alice/.export/json

Use this for column-level queries, joining file-first apps with data-first workflows, or inspecting the row that backs a given file.

Caution: writes through .tables/ bypass the history trigger: they mutate the database directly without producing entries in the workspace's .log/, .history/, or undo machinery. Use the file-first interface (/mnt/<workspace>/) for normal edits; reserve .tables/ for diagnostics or one-off fixes you don't want in the audit trail.

Schema exploration

Understand any database in seconds:

# See all tables ls /mnt/ orders/ users/ products/ shipments/ # Inspect a row cat /mnt/users/1.json {"id":1,"name":"Alice","email":"[email protected]","role":"admin"}

Row formats

Read rows in multiple formats by varying the file extension:

ExtensionExample
.jsoncat /mnt/users/123.json
.csvcat /mnt/users/123.csv
.tsvcat /mnt/users/123.tsv
.yamlcat /mnt/users/123.yaml

Row as directory

Navigate into a row to access individual columns as files:

ls /mnt/users/123/ # list columns cat /mnt/users/123/email.txt # read single column

Bulk export

Reading individual row files with tools like cat */* or grep -r works, but triggers a separate database query per file. For bulk reads, use .export/ to retrieve an entire table in one query:

# Data only (default) cat /mnt/orders/.export/csv # With column headers cat /mnt/orders/.export/.with-headers/tsv

Pipeline queries

.export/ returns every row. Pipeline queries push filtering, sorting, and pagination into the database so only matching rows are transferred:

cat /mnt/orders/.by/customer_id/123/.order/created_at/.last/10/.export/json
SegmentDescription
.by/Index lookup .by/column/value
.filter/Filter on any column .filter/column/value
.order/Sort by column .order/column
.columns/Select one or more specific columns .columns/col1,col2
.first/N/First N rows
.last/N/Last N rows
.sample/N/Random sample of N rows
.all/All rows (bypasses directory listing limit)
.export/Output format .export/csv, .export/json, .export/tsv

Segments can be chained in any order.

Write semantics (PATCH)

Write to rows using JSON or individual column files. JSON writes use PATCH semantics. Only the specified keys are updated:

# Update a single column echo '[email protected]' > /mnt/users/123/email.txt # PATCH update via JSON (only specified keys change) echo '{"email":"[email protected]","name":"A"}' > /mnt/users/123.json # Create a new row mkdir /mnt/users/456 # Delete a row rm -r /mnt/users/456/

Data-first writes are direct and permanent. Deletes have no trash and no undo. For reversible writes — logged changes, savepoints, and atomic rollback — use a file-first workspace with the history feature.

Ingestion with .import/

Bulk-load data from CSV, JSON, or YAML. The write mode is part of the path:

# Append rows cat data.csv > /mnt/orders/.import/.append/csv # Upsert by primary key cat data.csv > /mnt/orders/.import/.sync/csv # Replace entire table cat data.csv > /mnt/orders/.import/.overwrite/csv

Creating tables

Create new tables without a SQL client using the .create/ staging pattern. Create a staging directory, write a CREATE TABLE statement, then commit:

# Create a staging directory mkdir /mnt/.create/orders # View the auto-generated template cat /mnt/.create/orders/sql # Write your CREATE TABLE statement (or use emacs/vi/vim) echo "CREATE TABLE orders ( id SERIAL PRIMARY KEY, customer_id INTEGER NOT NULL, total NUMERIC(10,2), status TEXT DEFAULT 'pending', created_at TIMESTAMP DEFAULT NOW() )" > /mnt/.create/orders/sql # Validate (optional) touch /mnt/.create/orders/.test cat /mnt/.create/orders/test.log # Execute touch /mnt/.create/orders/.commit

Or as a one-liner for scripts:

mkdir /mnt/.create/orders && \ echo "CREATE TABLE orders (id SERIAL PRIMARY KEY, name TEXT)" > /mnt/.create/orders/sql && \ touch /mnt/.create/orders/.commit

Use touch .abort to cancel a staging directory. The same staging pattern works for modifying tables (table/.modify/), deleting tables (table/.delete/), and creating or deleting indexes (table/.indexes/.create/name/).

Agent skills

Agent skills

TigerFS ships with agent skills that teach the agent how to use mounted databases through file operations (Read, Write, Glob, Grep). The skills encode safe patterns like checking .info/count before listing large tables, using pipeline queries for efficient reads, and following recipes for common workflows.

Installation

Skills install automatically during curl -fsSL https://install.tigerfs.io | sh. The installer detects supported coding agents in your home directory and copies skills/tigerfs/ into each one's skills directory. Your agent loads the skill on its own when you work with a TigerFS mount, based on the description in SKILL.md. No explicit invocation is needed.

AgentInstall path
Claude Code~/.claude/skills/tigerfs/
Cursor~/.cursor/skills/tigerfs/
Codex CLI~/.agents/skills/tigerfs/
Gemini CLI~/.gemini/skills/tigerfs/
Windsurf~/.codeium/windsurf/skills/tigerfs/
Antigravity~/.gemini/antigravity/skills/tigerfs/
Kiro~/.kiro/steering/tigerfs/

If no agent is detected (or the installer runs non-interactively), skills are staged at ~/.config/tigerfs/skills/tigerfs/ and the installer prints a cp command for each detected agent.

Re-running the installer to upgrade TigerFS pulls in the latest skills and overwrites the skills/tigerfs/ directory at each install path. Any local edits inside skills/tigerfs/ will be lost. If you want to extend the skills, add your own files outside that directory (for example, a sibling skill under ~/.claude/skills/) so upgrades leave them untouched.

What's included

FilePurpose
SKILL.mdEntry point: mode selection, directory structure, quick reference
files.mdFile-first mode: markdown/plaintext apps, frontmatter, history
data.mdData-first mode: row-as-file, metadata, indexes, pipeline queries
ops.mdCLI reference: mount, create, fork, and manage databases
recipes.mdPractical patterns: task boards, knowledge bases, session context

Example interaction

Ask Claude Code to set up a task board and it follows the recipe automatically:

> Set up a task board on /mnt # Claude Code will: # 1. Create the app echo "markdown,history" > /mnt/.build/tasks # 2. Create board directories mkdir /mnt/tasks/todo /mnt/tasks/doing /mnt/tasks/done # 3. Write initial tasks cat > /mnt/tasks/todo/setup-ci.md << 'EOF' --- priority: high assignee: alice --- # Set up CI pipeline Configure GitHub Actions for the project. EOF

Example: data-first exploration

The skills teach the agent safe patterns for exploring unfamiliar databases -- check size first, sample before scanning, push filters into the database:

> What's in the orders table on /mnt? Show me recent high-value orders. # Claude Code will: # 1. Check table size first (iron law) cat /mnt/orders/.info/count # 847,000 # 2. Inspect schema cat /mnt/orders/.info/schema # 3. Sample a few rows to understand the data cat /mnt/orders/.sample/3/.export/json # 4. Query with pipeline (pushes filter to DB) cat /mnt/orders/.filter/status/completed/.order/total/.last/10/.export/json

Example: file-first management

For history-enabled workspaces, the skills teach the savepoint, operation-log, and undo paths, so you can ask for a checkpoint and roll back later in plain language:

> Set a savepoint before refactoring my notes, then undo it if the tests fail. # Claude Code will: # 1. Bookmark the current state echo '{"description":"before refactor"}' > /mnt/notes/.savepoint/before-refactor.json # 2. ...make the edits you asked for... # 3. Preview exactly what an undo would restore diff -ru /mnt/notes/.undo/to-savepoint/before-refactor /mnt/notes/ -x '.*' # 4. Roll everything back in one atomic operation touch /mnt/notes/.undo/to-savepoint/before-refactor/.apply

For finer control it reads the operation log and undoes selectively: by user, by a single entry, or everything since one.

> What did agent-7 change in the last hour? Undo just those edits. # 1. Look the file up by stable id (filenames aren't a .log/ index) file_id=$(cat /mnt/notes/.history/plan.md/.id) # 2. Read recent operations, filtered by that user cat /mnt/notes/.log/.by/user_id/agent-7/.last/10/.export/json # 3. Undo only agent-7's changes since the savepoint touch /mnt/notes/.undo/to-savepoint/before-refactor/.by/user_id/agent-7/.apply # 4. ...or reverse one specific operation by log id touch /mnt/notes/.undo/id/<log_id>/.apply
Configuration

Configuration

Config file

TigerFS reads configuration from:

~/.config/tigerfs/config.yaml

Run tigerfs config show to see all options and their current values.

YAML structure

# ~/.config/tigerfs/config.yaml # Connection defaults default_schema: public password_command: op read "op://Vault/pg/password" insecure_no_ssl: false # allow unencrypted remote connections # Backend default_backend: tiger # Filesystem behavior default_format: tsv # tsv, csv, or json dir_listing_limit: 10000 # max rows returned by ls dir_writing_limit: 100000 # max rows for write operations trailing_newlines: true # append newline to file reads no_filename_extensions: false # disable .txt/.json extensions query_timeout: 30s dir_filter_limit: 100000 # threshold for .filter/ value listing # Logging log_level: warn # debug, info, warn, error log_file: "" # default: stderr

Environment variables

All config keys are available as environment variables with the TIGERFS_ prefix (uppercase, underscored). Run tigerfs config show to see the full list of keys and their corresponding env variable names.

Precedence order

  1. Command-line flags (highest priority)
  2. Environment variables (TIGERFS_*)
  3. Config file (~/.config/tigerfs/config.yaml)
  4. Built-in defaults (lowest priority)

Password resolution

For postgres:// connections, passwords are resolved in order: connection string, password_command config option, PGPASSWORD environment variable, ~/.pgpass file. Cloud backends (tiger:, ghost:) retrieve credentials automatically via their respective CLIs.

TLS

Remote connections default to sslmode=require (any existing disable or prefer is upgraded; require, verify-ca, and verify-full are left alone). Localhost connections default to sslmode=disable. To opt out for remote hosts (for example, a test server without a valid certificate), set insecure_no_ssl: true or pass --insecure-no-ssl; TigerFS logs a warning when enforcement is off.

Additional internal tuning parameters (pool sizes, cache intervals, metadata refresh) are also available. Run tigerfs config show for a complete list.

Upgrading

Upgrading and migrations

To upgrade TigerFS, re-run the installer. It replaces the binary in place and refreshes agent skills (see Agent skills).

curl -fsSL https://install.tigerfs.io | sh

Schema migrations

Some releases change the database structures that TigerFS creates in a mounted database. The tigerfs migrate command detects these changes on a given database and applies them. Each migration is self-describing and runs inside a single transaction.

The command supports three modes:

# List pending migrations without touching the database tigerfs migrate tiger:my-db --describe # Preview the SQL that would run tigerfs migrate tiger:my-db --dry-run # Execute pending migrations (wrapped in a transaction) tigerfs migrate tiger:my-db

Connection strings follow the same conventions as tigerfs mount: tiger:ID, ghost:ID, or a full postgres:// URL. Pass --schema NAME to target a schema other than the database's default search path.

Example: 0.6.0 backing-table migration

TigerFS 0.6.0 moved synth backing tables from _name in the user schema to name in a dedicated tigerfs schema, with a view in the user schema pointing to the new location. Existing databases mounted before 0.6.0 need to run tigerfs migrate to pick up the new layout.

# See what would change tigerfs migrate tiger:my-db --describe move-backing-tables: Move synth backing tables from _name in user schema to name in tigerfs schema - _notes - _blog # Inspect the SQL tigerfs migrate tiger:my-db --dry-run # Apply tigerfs migrate tiger:my-db

Running the migration a second time is safe; --describe will report no pending migrations once every table has been moved.

Example: 0.6 → 0.7 history-format migration

TigerFS 0.7 adds the operation log, savepoints, and undo. Workspaces created on 0.6 with history enabled need tigerfs migrate to pick up the new format: it adds parent_id/filetype/filename columns to backing tables and rebuilds the history triggers. The migration is idempotent. Fresh 0.7 installs are unaffected.

Undo boundary. Undo of log entries created before the migration is blocked (returns EPERM), because pre-migration history has lossy parent_id information. Those entries remain fully readable in .log/ and .history/. You just can't roll them back. Everything written after the migration is undoable as normal.