Skip to main content
Install SmolFS on the machine where your agent needs a durable workspace folder. Start with the command line tool, then add a Python or TypeScript package only if your agent runner should manage SmolFS from code.

​
Install the CLI

Run the installer: 
curl -fsSL https://raw.githubusercontent.com/CelestoAI/smolfs/main/scripts/install.sh | sh
The installer downloads the latest stable CLI release for Linux or macOS and installs SmolFS’ managed storage backend.
When installation finishes, smolfs should be available from your shell. If the installer prints a PATH hint, add that directory to your PATH and open a new terminal.

​
Check the machine

Run doctor before creating a workspace: 
smolfs doctor
doctor checks the local storage backend and mount support, which means the operating system feature that lets SmolFS show a workspace as a folder. If the storage backend is missing, install it: 
smolfs doctor --install

​
Install SDKs

The SDKs still need the CLI storage backend on the machine that opens workspaces.
Install the Python package in a project:
uv add smolfs
SmolFS requires Python 3.9 or newer.

​
Source fallback

Use the source checkout when a release asset is not available for your platform or you are changing SmolFS itself: 
git clone https://github.com/CelestoAI/smolfs.git
cd smolfs
cargo build -p smolfs-cli
./target/debug/smolfs doctor

​
Installer options

Use these only when you need a non-default install:
VariableWhat it does
SMOLFS_VERSION=devInstalls the latest successful CLI build from main.
SMOLFS_INSTALL_BACKEND=0Installs the CLI without installing the managed storage backend.
SMOLFS_INSTALL_PYTHON=1Installs the Python SDK after installing the CLI.
SMOLFS_INSTALL_DIR=/path/binChanges where the smolfs command is installed.
SMOLFS_HOME=/path/homeChanges where SmolFS stores local config, volume records, logs, and local dev data.
Next, run the quickstart.
Last modified on June 24, 2026