# Installation

> Install paths (curl installer, go install, releases), platform prerequisites (Linux FUSE, macOS NFS, Docker), and verification commands.

- Repository: timescale/tigerfs
- GitHub: https://github.com/timescale/tigerfs
- Human docs: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3
- Complete Markdown: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/llms-full.txt

## Source Files

- `scripts/install.sh`
- `.goreleaser.yaml`
- `go.mod`
- `docs/spec.md`
- `scripts/test-install.sh`

---

---
title: "Installation"
description: "Install paths (curl installer, go install, releases), platform prerequisites (Linux FUSE, macOS NFS, Docker), and verification commands."
---

TigerFS ships as a single static `tigerfs` binary built with GoReleaser (`CGO_ENABLED=0`) for Linux and macOS on `x86_64` and `arm64`. Release archives bundle the CLI, `skills/tigerfs/` agent instructions, and SHA256 checksums served from `https://install.tigerfs.io`. Mounting requires PostgreSQL reachability; the filesystem backend is FUSE on Linux and an in-process NFS server on macOS.

## Install paths

<Tabs>
<Tab title="Curl installer (recommended)">

The curl installer downloads a versioned release archive, verifies its checksum, installs the binary, and optionally copies agent skills.

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

Pin a version or override install location:

```bash
VERSION=v0.7.0 curl -fsSL https://install.tigerfs.io | sh
INSTALL_DIR=/usr/local/bin curl -fsSL https://install.tigerfs.io | sh
```

| Variable | Default | Effect |
|----------|---------|--------|
| `BASE_URL` | `https://install.tigerfs.io` | CDN root for `latest.txt` and `releases/{version}/` |
| `VERSION` | Latest from `/latest.txt` | Release tag; normalized to `v*` prefix |
| `INSTALL_DIR` | `~/.local/bin` if `~/.local` exists, else `~/bin` | Binary destination |
| `TIGERFS_INTERACTIVE` | unset | Set to `1` to force the agent-skills menu in non-TTY contexts |

**Installer dependencies:** `curl` or `wget`, `tar`, and `sha256sum` or `shasum`.

**Download layout:** `{BASE_URL}/releases/{version}/tigerfs_{OS}_{arch}.tar.gz` plus a sibling `.sha256` file. Supported OS values are `Linux` and `Darwin`; architectures are `x86_64` and `arm64`.

On macOS, the installer clears the Gatekeeper quarantine attribute (`xattr -d com.apple.quarantine`) when present.

</Tab>
<Tab title="Go install">

Build and install the latest module release into your Go binary path:

```bash
go install github.com/timescale/tigerfs/cmd/tigerfs@latest
```

Requires Go **1.25.1** or newer (see `go.mod`). Agent skills are **not** copied by `go install`; clone the repository or use the curl installer to get `skills/tigerfs/`.

</Tab>
<Tab title="GitHub releases">

Tagged releases (`v*.*.*`) trigger `.github/workflows/release.yml`, which runs GoReleaser and publishes:

- **GitHub Releases** — per-platform `.tar.gz` archives and checksums
- **S3** (`tigerfs-releases`) — same artifacts under `releases/{tag}/`, plus root `latest.txt` and `install.sh` on stable (non-prerelease) tags

Archive names follow `tigerfs_{Os}_{Arch}.tar.gz` (for example `tigerfs_Linux_x86_64.tar.gz`). Each archive contains the `tigerfs` binary, `README.md`, `docs/spec.md`, and `skills/tigerfs/*`.

Download manually, verify the `.sha256` sidecar, extract, and place `tigerfs` on your `PATH`.

</Tab>
<Tab title="Build from source">

For development or unreleased commits:

```bash
git clone https://github.com/timescale/tigerfs.git
cd tigerfs
go build -o bin/tigerfs ./cmd/tigerfs
```

Optional snapshot matching release builds:

```bash
goreleaser release --snapshot --clean
./dist/tigerfs_*/*/tigerfs version
```

Skills live at `skills/tigerfs/` in the repository tree.

</Tab>
</Tabs>

### Agent skills (curl / release archives)

Release archives include `skills/tigerfs/` (`SKILL.md`, `files.md`, `data.md`, `ops.md`, `recipes.md`). After binary install, `scripts/install.sh`:

- **Interactive (TTY or `TIGERFS_INTERACTIVE=1`):** prompts to install skills into detected agents (Claude Code, Cursor, Codex CLI, Gemini CLI, Windsurf, Antigravity, Kiro) or skip
- **Non-interactive (`curl | sh`):** stages skills to `~/.config/tigerfs/skills/tigerfs/` with copy hints for detected agents

Upgrades replace the target `tigerfs` skill directory (`rm -rf` then `cp -r`) so stale skill files are removed.

Validate the installer locally:

```bash
./scripts/test-install.sh
```

## Platform prerequisites

TigerFS needs a running **PostgreSQL** database (local, remote, or Tiger/Ghost backends). Filesystem prerequisites depend on the host OS.

```mermaid
flowchart LR
  subgraph clients["Client tools"]
    LS["ls / cat / grep"]
  end
  subgraph tigerfs["tigerfs process"]
    OPS["fs.Operations"]
  end
  subgraph backends["OS filesystem backend"]
    FUSE["Linux: go-fuse"]
    NFS["macOS: go-nfs in-process"]
  end
  PG[(PostgreSQL)]
  LS --> FUSE & NFS
  FUSE & NFS --> OPS --> PG
```

| Platform | Filesystem backend | Host prerequisites |
|----------|-------------------|-------------------|
| **Linux** | FUSE (`hanwen/go-fuse/v2`) | FUSE userspace support; `/dev/fuse` present. CI installs `fuse` / `libfuse-dev`. Unprivileged mounts typically require membership in the `fuse` group. |
| **macOS** | In-process NFS v3 (`go-nfs`) | No FUSE or kernel extension install. Uses built-in `mount_nfs`. |
| **Windows** | WinFsp (planned) | Documented in `docs/spec.md` as requiring WinFsp; **not** in the current curl installer OS matrix (`Linux` / `Darwin` only). |
| **Docker** | Linux FUSE inside container | Privileged container, `/dev/fuse` device, `SYS_ADMIN` capability for mount workflows |

<Warning>
Managed platforms without FUSE device access (for example AWS Fargate, Cloud Run, Kubernetes without privileged pods) cannot run TigerFS mounts as implemented today.
</Warning>

### Linux FUSE setup

On Debian/Ubuntu-family systems:

```bash
sudo apt-get update
sudo apt-get install -y fuse libfuse-dev
```

Fedora/RHEL-style:

```bash
sudo dnf install fuse3
```

Confirm the device node exists before mounting:

```bash
test -e /dev/fuse && echo "FUSE available"
```

Integration and stress Docker stacks use `privileged: true`, map `/dev/fuse`, and add `SYS_ADMIN` (see `test/docker/docker-compose.test.yml`, `test/stress/docker/docker-compose.yml`).

### macOS

No additional filesystem packages. TigerFS selects the NFS backend at compile time (`mount_darwin.go`). The curl installer strips quarantine on the installed binary.

### Docker

**Root `Dockerfile`** — multi-stage Alpine image with `fuse` runtime packages; intended as a container entrypoint for the CLI (`ENTRYPOINT ["/usr/local/bin/tigerfs"]`).

**Demo stack** (`scripts/demo/docker/`) — Ubuntu-based image with `fuse3`, PostgreSQL client tools, and a prebuilt `tigerfs` binary. Compose runs the `tigerfs` service `privileged: true` against a `timescale/timescaledb-ha:pg18` database.

Typical FUSE mount flags in container docs and spec:

```bash
docker run --rm -it \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  -v /path/to/mount:/mnt/db \
  tigerfs mount postgres://user:pass@host:5432/db /mnt/db
```

Use `./scripts/demo/demo.sh start` for a guided demo (auto-detects macOS NFS vs Linux Docker FUSE). See the demo environment page for `demo.sh` commands and seed data.

<Note>
Package managers (Homebrew, apt, yum) are listed in `docs/spec.md` as **Phase 2 (deferred)**. The supported distribution paths today are curl install, `go install`, GitHub/S3 releases, and source build.
</Note>

## Verification

Run these after any install path before attempting a mount.

<Steps>
<Step title="Confirm binary and version">

```bash
command -v tigerfs
tigerfs version
```

<RequestExample>

```bash
$ tigerfs version
TigerFS v0.7.0
Build time: 2026-...
Git commit: ...
Go version: go1.25.1
Platform: darwin/arm64
```

</RequestExample>

</Step>
<Step title="Test database connectivity">

Verify credentials without mounting:

```bash
tigerfs test-connection postgres://localhost:5432/mydb
```

Or use `PGHOST`, `PGUSER`, `PGDATABASE`, etc., or Tiger Cloud `TIGER_SERVICE_ID` per your config. The command prints PostgreSQL version, current database/user, and accessible schema/table counts (30s timeout).

</Step>
<Step title="Optional: run install script tests">

From a source checkout:

```bash
./scripts/test-install.sh
```

Exercises download, checksum verification, binary placement, and skills staging/copy paths against a `file://` mock CDN.

</Step>
</Steps>

### PATH

If `tigerfs` is not found, ensure the install directory is on `PATH`:

```bash
export PATH="$HOME/.local/bin:$PATH"   # default curl target when ~/.local exists
# or
export PATH="$HOME/bin:$PATH"
```

The curl installer prints this hint when the install dir is missing from `PATH`.

### Install script integration test (maintainers)

`scripts/test-install.sh` validates non-interactive staging, interactive agent selection, skip behavior, and upgrade cleanup of stale skill files. Requirements match `install.sh`: `sh`, `tar`, `curl` or `wget`, `sha256sum` or `shasum`.

## Release and CDN topology

```text
git tag vX.Y.Z
    │
    ▼
.github/workflows/release.yml  →  GoReleaser (.goreleaser.yaml)
    │                              ├─ linux/darwin × amd64/arm64
    │                              ├─ tar.gz + checksums
    │                              ├─ GitHub Releases
    │                              └─ S3 tigerfs-releases/releases/{tag}/
    ▼
CloudFront install.tigerfs.io
    ├─ /install.sh          (from scripts/install.sh on stable tags)
    ├─ /latest.txt          (current version string)
    └─ /releases/{tag}/tigerfs_{OS}_{arch}.tar.gz[.sha256]
```

GoReleaser embeds version metadata via ldflags (`Version`, `BuildTime`, `GitCommit` in `internal/tigerfs/cmd`). Stable releases also upload `latest.txt` and invalidate CloudFront paths `/latest.txt` and `/install.sh`.

## What to do next

After installation and `test-connection` succeed, mount a database and explore with standard Unix tools. Use `--debug` on the CLI for structured stderr logs when mounts fail with errno-only tool messages.

## Related pages

<CardGroup>
<Card title="Quickstart" href="/quickstart">
First mount with `postgres://` or `tiger:`, explore with `ls`/`cat`, and demo success signals.
</Card>
<Card title="Platform backends" href="/platform-backends">
Linux FUSE vs macOS NFS adapters, write/commit behavior, and mount registry.
</Card>
<Card title="Connection reference" href="/connection-reference">
`postgres://` URIs, TLS/`sslmode=require`, localhost exemptions, and pool settings.
</Card>
<Card title="Agent skills" href="/agent-skills">
Bundled `skills/tigerfs` pack, install-time staging, and agent directory layout.
</Card>
<Card title="Demo environment" href="/demo-environment">
`demo.sh` workflows, Docker vs macOS native, and seeded exploration data.
</Card>
<Card title="Develop and test" href="/develop-and-test">
Source builds, `go test`, Docker FUSE integration tests, and release checklist.
</Card>
</CardGroup>