ValetFS GitHub Pages

ValetFS Quick Install Overview

ValetFS is a zero-backend, P2P, in-memory virtual file system desktop daemon. It is designed to expose short-lived tokens/keys to AI agents only while a paired mobile app allows it.

This repository contains the Go-based daemon (cmd/valetfs) and a Cloudflare Worker signaling stub for WebRTC bootstrap (signaling/).

Core Project Components

internal/vfs: in-memory FS and FUSE/WebDAV mounting
internal/webrtc: pion-based P2P connection + signaling integration
internal/sync: commits manifest lines with hash/size/path only (no token body)
internal/daemon: daemon lifecycle and local dev API
scripts/install.sh: auto-download and install script for release binaries

Install with curl + install.sh (Recommended)

On Linux, install the latest release with this one-liner:

curl -fsSL https://winm2m.github.io/valet-fs/install.sh | bash

The installer detects OS/architecture (amd64, arm64), downloads the matching binary from GitHub Releases, and installs it to /usr/local/bin/valetfs by default.

Optional Parameters

Install a specific version: set VALETFS_VERSION=v0.2.0
Change install path: set INSTALL_DIR=/custom/bin
Refuse to install unless the signature verifies: set VALETFS_REQUIRE_SIGNATURE=1

curl -fsSL https://winm2m.github.io/valet-fs/install.sh | VALETFS_VERSION=v0.2.0 INSTALL_DIR=$HOME/.local/bin bash

Verifying what you installed

This binary ends up holding your credentials, so it is worth knowing where it came from. Every release publishes a SHA256SUMS covering all artifacts, signed with cosign keyless — there is no private key, the signature is bound to the release workflow’s identity and recorded in a public transparency log.

The installer checks the checksum always, and checks the signature when cosign is installed. If it is not, the installer says so rather than staying quiet: a checksum served from the same place as the binary proves the download was not corrupted, and nothing more. Install cosign and re-run with VALETFS_REQUIRE_SIGNATURE=1 to make a missing or invalid signature a hard failure.

To verify a release by hand:

V=v0.2.0
base=https://github.com/WinM2M/valet-fs/releases/download/$V
curl -fLO $base/SHA256SUMS
curl -fLO $base/SHA256SUMS.sig
curl -fLO $base/SHA256SUMS.pem
cosign verify-blob \
  --certificate SHA256SUMS.pem \
  --signature SHA256SUMS.sig \
  --certificate-identity-regexp '^https://github.com/winm2m/valet-fs/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

One thing this does not cover: an attacker who can change the release workflow itself can still produce a valid signature. What they cannot do is produce one quietly. The ValetFS iOS app also shows the digest it expects, and the app reaches you through Apple rather than GitHub, so the two have to agree.

AI agent skill (Claude Code)

If you hand a connection key to a skill-capable agent, install the ValetFS skill on that machine as well. It makes the agent check your vault before reading credentials from disk or environment variables — in every later session, not just the one where you pasted the key.

curl -fsSL https://winm2m.github.io/valet-fs/install-skill.sh | bash

Installs to ~/.claude/skills/valetfs/. Set SKILL_DIR= to scope it to a single project instead.

Quick Start After Install

valetfs serve --dev
valetfs status

The daemon starts a local control API and WebDAV endpoint on loopback, and keeps running even when FUSE mounting is unavailable.

Two-Device Pairing Test (Vault + Serve)

You can validate the new vault-origin workflow with two machines: one runs serve as remote daemon, the other runs vault as controller.

Device A (serve target)

valetfs serve

If --signaling is omitted, default signaling URL is https://valetfs-signaling.winm2m.workers.dev. Keep this process running and copy the printed Session ID: ... value.

Device B (vault origin/controller)

export VALETFS_VAULT_PASSWORD='change-me'
valetfs vault init
valetfs vault add ./my-key.pem fs:/keys/my-key.pem
valetfs vault pair <SESSION_ID>

Optional follow-up commands:

valetfs vault sync <SESSION_ID> --signaling https://valetfs-signaling.winm2m.workers.dev
valetfs vault status <SESSION_ID> --signaling https://valetfs-signaling.winm2m.workers.dev
valetfs vault unmount <SESSION_ID> --signaling https://valetfs-signaling.winm2m.workers.dev

If follow-up commands time out when reconnecting to the same session, create a new serve session and pair again.

Verbose Mode for Pairing Diagnostics

If pairing fails with timeout, run both sides with verbose logs to inspect signaling, claim, answer, and ICE candidate exchange.

valetfs serve -v
valetfs vault -v pair <SESSION_ID>