Spherefiles
Spherefiles is the file browser for a SphereStor. Browse the directory tree, upload files in, download files out, create folders, rename and delete, archive a folder into a tarball, restore from a tarball — all without rebuilding your container or shelling in.
/uploads
/var/db
/backup.tar.gzSpherefiles isn't a separate storage product. It's the operations surface on top of SphereStor: the same disk your service mounts at /data, browsed through the console (or the API) when you need to put something on it, get something off, or reorganize what's there.
When to reach for it
| Situation | Why Spherefiles fits |
|---|---|
| Seed a database | Drop a SQLite file, a SQL dump, or fixture data straight onto the SphereStor before your service starts. |
| Get logs / artifacts out | Download log files, generated reports, or model checkpoints without setting up SCP. |
| Restore from a backup | Upload a .tar.gz from your local machine; Spherefiles can extract it into place. |
| Snapshot before a risky change | Tar a directory inside the SphereStor, download it, keep it around. |
| Clear stale uploads | Delete a folder full of caches or old user uploads without redeploying. |
| Inspect what's on disk | Browse the tree visually instead of guessing what your container wrote where. |
If you need to add or remove a managed datastore (SphereDB, SphereCache, SphereQueue), see those pages — Spherefiles only deals with raw files on a SphereStor.
What you can do
Spherefiles exposes one operation per file-system action you'd normally run with a shell:
| Action | What it does |
|---|---|
| List | Directory listing for a path on the SphereStor. |
| Storage usage | Used / total / available bytes for the SphereStor. |
| New folder | Create a directory at a path. |
| Upload | Push a file from your machine to a path on the SphereStor. |
| Download | Pull a file from a path on the SphereStor to your machine. |
| Rename | Rename a file or folder. |
| Delete | Delete a file or folder. |
| Details | Read file metadata (size, permissions, timestamps). |
| Tar | Archive a directory into a .tar.gz on the SphereStor. |
| Untar | Extract a .tar.gz (already on the SphereStor) into a directory. |
The console wraps these in a file-browser UI; the API exposes each as a POST endpoint.
Use it from the console
- Open the project and environment containing the SphereStor.
- Click Storage in the environment sidebar.
- Pick the SphereStor you want to browse → Files tab.
- The first time you open it, the platform spins up a lightweight file-browser pod that mounts the SphereStor read-write. Wait a few seconds for it to become ready.
- Browse, upload, download, tar, restore. Changes are written straight to the SphereStor and visible to any service that mounts it.
The file-browser pod shuts down on idle — there's no cost when you're not using it.
Use it from the API
Every Spherefiles operation is a POST against /v2/spherefiles/*, scoped by spherestor_id and environment_id in the body.
Get an API token from Settings → User tokens in the console — see API keys. If your user belongs to more than one account, send x-account-id: <ACCOUNT_ID> to disambiguate.
How it works
Spherefiles operations don't run inside your service container. They run in a small, transient file-browser pod that the platform spins up in your environment when you start using Spherefiles, mounting the target SphereStor read-write.
- Your service can keep running while you upload, download, tar, or restore. The SphereStor is shared between your service (at its mount path) and the file-browser (at
/). - The file-browser pod shuts down on idle — there's no cost when you're not using it.
- Spherefiles never ships file contents through the docs API endpoints. Downloads stream straight from the file-browser pod to your client; uploads stream the reverse direction.
Honest limits
- Single SphereStor scope. Each Spherefiles session operates on one SphereStor at a time. To move files between SphereStor volumes, download then upload, or tar then untar across two sessions.
- Single-writer rule still applies. Spherefiles can write to a SphereStor while a service is reading from it, but two writers (your service + Spherefiles, or two Spherefiles sessions) racing on the same file isn't safe. Stop the service if you're doing a large restore.
- No file-level versioning. Renaming or deleting is immediate. To keep history, tar before you change things.
- Tar runs synchronously. Large archives take real time and the call doesn't return until they finish. For multi-GB archives, prefer a background job that calls the tar endpoint and checks completion.
- No symlinks across SphereStor. A symlink that points outside the SphereStor's root is rejected on creation/restore.
What's next
- SphereStor — the storage volume Spherefiles browses.
- Spherelets — the compute units that mount SphereStor at runtime.
- Environments — where SphereStor lives.