(beta) persistent filesystem

SPX gives each project a persistent filesystem mounted at /data/local-fs inside the deployed microVM.

Use it for files your app needs to keep across deployments, such as small uploaded files, generated artifacts, caches you intentionally want to keep, or SQLite databases during prototyping.

Runtime path

Inside your deployed app, the persistent filesystem is available at:

/data/local-fs

SPX also sets an environment variable:

SPX_LOCAL_FS=/data/local-fs

Prefer the environment variable in app code so the path stays explicit:

import os
from pathlib import Path

LOCAL_FS = Path(os.environ["SPX_LOCAL_FS"])

uploads = LOCAL_FS / "uploads"
uploads.mkdir(parents=True, exist_ok=True)

path = uploads / "hello.txt"
path.write_text("hello from persistent storage\n")

What persists

Files under /data/local-fs persist across spx run deployments for the same project.

Files outside /data/local-fs should be treated as deployment runtime state. In particular, SPX replaces uploaded application code under /data/app on every deploy.

/data/app       replaced on each deploy
/data/local-fs  persists across deploys for the same project

Scope

Persistent filesystem state is scoped to the SPX project.

Running spx run main.py again for the same project reuses the same /data/local-fs contents. A different project gets a different persistent filesystem, even if it belongs to the same developer account.

Beta

The beta runtime supports the same persistent filesystem contract.

Beta routing is separate from production:

Production and beta run on separate Host VMs. Their microVM networks and persistent filesystems are independent, even if private VM IPs overlap internally.

Limits

New project filesystems are currently created with a fixed size configured by the platform. Treat /data/local-fs as local project storage, not object storage.

For durable production user uploads or large blob storage, prefer an external object store once your app outgrows local project storage.