> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SmolFS SDKs

> Use SmolFS from Python or TypeScript when an agent runner should manage durable workspace folders from code.

Use the Python or TypeScript package when your agent runner should create, open, save, and close SmolFS workspaces from code. Install and check the command line tool first so the local storage backend is ready.

## Install

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    uv add smolfs
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @celestoai/smolfs
    npm install --save-dev tsx typescript @types/node
    ```
  </Tab>
</Tabs>

## Local workspace example

<Tabs>
  <Tab title="Python">
    ```python quickstart_smolfs.py theme={null}
    from pathlib import Path
    from smolfs import SmolFS, doctor

    report = doctor()
    print("SmolFS home:", report["home"])

    fs = SmolFS.from_env()
    volume = fs.ensure_volume("demo", dev=True)
    mount = fs.mount(volume.name, "./workspace")
    workspace = Path(mount.mountpoint)

    try:
        (workspace / "hello.txt").write_text("hello from SmolFS\n")
        fs.flush(volume.name)
        print((workspace / "hello.txt").read_text().strip())
    finally:
        fs.unmount(volume.name)
    ```

    Run it:

    ```bash theme={null}
    python3 quickstart_smolfs.py
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript quickstart-smolfs.ts theme={null}
    import { SmolFS, doctor } from "@celestoai/smolfs";
    import { readFile, writeFile } from "node:fs/promises";
    import { join } from "node:path";

    async function main() {
      const report = doctor();
      console.log("SmolFS home:", report.home);

      const fs = SmolFS.fromEnv();
      const volume = fs.ensureVolume({ name: "demo", dev: true });
      const mount = fs.mount({ name: volume.name, path: "./workspace" });
      const file = join(mount.mountpoint, "hello.txt");

      try {
        await writeFile(file, "hello from SmolFS\n");
        fs.flush(volume.name);
        console.log((await readFile(file, "utf8")).trim());
      } finally {
        fs.unmount(volume.name);
      }
    }

    main().catch((error) => {
      console.error(error);
      process.exit(1);
    });
    ```

    Run it:

    ```bash theme={null}
    npx tsx quickstart-smolfs.ts
    ```
  </Tab>
</Tabs>

Both examples print the SmolFS home path and then:

```text theme={null}
hello from SmolFS
```

## Current surface

| Capability                           | Python               | TypeScript          |
| ------------------------------------ | -------------------- | ------------------- |
| Check local setup                    | `doctor()`           | `doctor()`          |
| Create a client from the environment | `SmolFS.from_env()`  | `SmolFS.fromEnv()`  |
| Create a new volume                  | `init(...)`          | `init(...)`         |
| Create or reuse a volume             | `ensure_volume(...)` | `ensureVolume(...)` |
| Open a workspace folder              | `mount(...)`         | `mount(...)`        |
| Save recent writes                   | `flush(...)`         | `flush(...)`        |
| Close a workspace folder             | `unmount(...)`       | `unmount(...)`      |
| Inspect volumes                      | `status(...)`        | `status(...)`       |

<Note>
  The SDKs are intentionally thin in this early release. Prefer the lifecycle shown above and expect details to move as SmolFS settles.
</Note>