Registry — LiveFolders

Installing Tools

Once you have LiveFolders installed, any registry tool is one command away:

# Install by owner/name slug livefolders install owner/toolname # Install a specific version (git tag) livefolders install owner/toolname@v1.2.0 # Install, then mount to make it available immediately livefolders install owner/toolname && livefolders mount

The CLI resolves the slug through the registry API, clones or downloads the folder.yaml from the source repository, and adds the tool to your local config. Re-running livefolders mount (or if it’s already running, the hot-reload picks it up within ~1 second) makes the tool’s files appear under .livefolders/tools/<name>/.

You can also search the registry from the command line or browse it on the web:

Action	Command / URL
Install	`livefolders install owner/name`
Search (web)	registry.livefoldersfs.org
Tool detail page	`registry.livefoldersfs.org/owner/name`
Resolve API	`GET /api/resolve/owner/name`

Publishing a Tool

Publishing is free and open to anyone. You need a public GitHub repository with a folder.yaml in the root. The registry verifies ownership via a GitHub personal access token — the token is used in-flight and never stored.

Step 1 — Create your folder.yaml

Place a folder.yaml in the root of your GitHub repository. Here is a minimal example:

name: myweather description: Get current weather for any city. files: - name: forecast type: write_invoke description: Write a city name, read back the forecast. input: type: string min_length: 1 max_length: 100 handler: >- curl -s "https://wttr.in/${LIVEFOLDERS_INPUT}?format=3" - name: how_to.md type: readonly

See the full folder.yaml reference below for all supported fields.

Step 2 — Create a GitHub personal access token

Go to GitHub → Settings → Developer settings → Personal access tokens and create a fine-grained token (or classic token) with at least read access to repository contents for the repo you want to publish. The token is only used to confirm you own the repo; it is discarded after the request.

Step 3 — Publish

Post to the registry API:

curl -s -X POST https://registry.livefoldersfs.org/api/publish \ -H "Content-Type: application/json" \ -d '{"token": "ghp_YOUR_TOKEN", "repo": "your-github-username/your-repo"}'

On success:

{"ok":true,"url":"https://registry.livefoldersfs.org/your-github-username/your-repo"}

⚠ Rate limit: 10 publishes per hour per IP. Re-publishing the same repo updates the existing listing (description, timestamps). Download counts are preserved.

What gets listed

Field	Source
Name	GitHub repo slug (`owner/name`)
Description	GitHub repository description
Repository URL	GitHub repo HTML URL
Download count	Incremented on each `livefolders install`
Versions	Git tags on the repository
Published / Updated	Timestamps set by the registry

Set a clear GitHub repo description before publishing — it becomes your tool’s tagline in the index.

folder.yaml Reference

A folder.yaml is 6–50 lines of YAML. No server process, no imports, no build step. The LiveFolders runtime reads it at mount time and hot-reloads it within ~1 second whenever you save a change.

Top-level fields

Field	Required	Description
`name`	Yes	Tool name — becomes the directory under `.livefolders/tools/`
`description`	Yes	One-line summary shown in `index.md` and the registry
`files`	Yes	List of virtual file definitions (see below)
`secrets`	No	List of required env var names; users prompted at install
`state_file`	No	Path to a persistent state file; injected as `LIVEFOLDERS_STATE_FILE`

File types

Type	Trigger	Use when…
`read_invoke`	LLM reads the file	No input needed — e.g. fetch a list, get current status
`write_invoke`	LLM writes the file	Input required — e.g. query, transform, command
`readonly`	—	Static content; no handler runs — good for `how_to.md`

Per-file fields

Field	Applies to	Description
`name`	All	Filename in the virtual directory
`type`	All	`read_invoke`, `write_invoke`, or `readonly`
`description`	All	Shown in `how_to.md` and `schema.json`
`handler`	Invoke types	Shell command or script path to execute
`input.type`	`write_invoke`	`string` or `json`
`input.min_length`	`write_invoke`	Minimum input byte length
`input.max_length`	`write_invoke`	Maximum input byte length
`input.pattern`	`write_invoke`	Regex the input must match
`input.schema`	`write_invoke`	JSON Schema block for structured input
`timeout`	Invoke types	Seconds before the handler is killed (default: 30)
`network`	Invoke types	`true` to allow outbound network (sandbox default: blocked)
`pipe`	Invoke types	List of endpoint names to chain — stdout of one feeds stdin of next

Full example

name: devtools description: A set of developer utilities — base64, JSON format, and UUID generation. secrets: - OPENAI_API_KEY # prompted at install, stored in secrets.env files: - name: how_to.md type: readonly - name: b64encode type: write_invoke description: Base64-encode any string. input: type: string min_length: 1 max_length: 4096 handler: echo -n "${LIVEFOLDERS_INPUT}" | base64 - name: jsonformat type: write_invoke description: Pretty-print JSON. input: type: json handler: echo "${LIVEFOLDERS_INPUT}" | jq . - name: uuid type: read_invoke description: Generate a random UUID v4. handler: python3 -c "import uuid; print(uuid.uuid4())" - name: summarise type: write_invoke description: Summarise any text with GPT-4o-mini. network: true input: type: string min_length: 10 handler: >- curl -s https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer ${OPENAI_API_KEY}" \ -H "Content-Type: application/json" \ -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarise: ${LIVEFOLDERS_INPUT}\"}]}" \ | jq -r '.choices[0].message.content'

Tips for a Good Listing

✓ Write a clear repo description

The GitHub repository description becomes your tool’s one-liner in search results. Keep it under 80 characters and lead with what the tool does, not what it is.

✓ Add a how_to.md file

A readonly file named how_to.md is the first thing an LLM reads. Describe each endpoint, expected inputs, and example outputs. The runtime auto-generates a basic version if you omit it, but a hand-crafted one is better.

✓ Validate all inputs

Use min_length, max_length, pattern, and schema to reject bad input before the handler runs. The runtime returns a structured [ERROR:INVALID_INPUT] message — LLMs handle these cleanly.

✓ Tag your releases

Git tags become installable versions: livefolders install owner/name@v1.0.0. Push a tag before publishing so users can pin to a stable release.

✓ Declare secrets up front

If your tool needs an API key, list it under secrets:. Users are prompted at install time and the key is stored in a local secrets.env. Never hardcode credentials in the handler.

✓ Set network: true only if needed

The sandbox blocks outbound network by default — a good default for tools that don’t need it. Only set network: true on endpoints that genuinely call external services, so users can see exactly what reaches the internet.

Registry API

The registry exposes a small REST API consumed by the CLI and available for integrations. All endpoints return JSON. Rate limits apply per IP.

Endpoint	Method	Description	Rate limit
`/api/publish`	`POST`	Publish or update a tool listing	10 / hour
`/api/search?q=`	`GET`	Full-text search across name, description, and tags	60 / minute
`/api/resolve/:owner/:name`	`GET`	Resolve a slug to repo URL and metadata (used by the CLI)	60 / minute
`/api/tools/:owner/:name`	`GET`	Full tool record (all stored fields)	60 / minute
`/api/tools/:owner/:name/downloads`	`POST`	Increment download counter (called by CLI on install)	30 / minute

Publish request body:

POST /api/publish Content-Type: application/json { "token": "ghp_YOUR_GITHUB_TOKEN", "repo": "owner/repo-name" }

Search example:

curl "https://registry.livefoldersfs.org/api/search?q=weather"

📦 Registry

What Is the Registry?