Skip to main content

File system paths reference

Fused exposes two file systems to UDFs: a mounted disk at /mount/ and a private S3 home directory at s3://fused-users/<org>/<username>/. Both are scoped at the organization level.

This page maps every directory under each location so you know where things live and what they contain.

/mount/ — mounted disk​

Everything written here is shared across all UDFs in your environment and persists between executions. The fused-system/ subdirectory is managed by the Fused runtime — do not write to it directly.

/mount/
├── fused-system/
│   ├── cached_data/
│   │   └── {udf_name}/
│   └── logs/
│       └── {YYYY-MM-DD}/
│           └── {HHMM}/
│               └── {user_email}/
│                   └── {request_id}/
│                       ├── metadata.json
│                       ├── udf.json
│                       ├── stdout.log
│                       └── stderr.log

cached_data/​

Output cache for @fused.cache. Each subdirectory corresponds to a UDF by name; entries within are keyed by a hash of the function arguments.

/mount/fused-system/cached_data/
└── {udf_name}/
    └── data_{hash}

logs/​

Per-request execution logs for UDF runs. One directory per request, organized by date and time.

/mount/fused-system/logs/
└── {YYYY-MM-DD}/
    └── {HHMM}/
        └── {user_email}/
            └── {request_id}/
                ├── metadata.json    ← user_email, udf_name, collection_name, execution_time_seconds
                ├── udf.json         ← UDF code at time of execution (key: "code")
                ├── stdout.log       ← captured stdout
                └── stderr.log       ← captured stderr; non-empty means an error occurred

List all execution directories for a date:

@fused.udf
def udf(datestr: str = "2026-05-12"):
    import glob
    import pandas as pd

    dirs = glob.glob(f"/mount/fused-system/logs/{datestr}/*/*/*")
    df = pd.DataFrame({"file_path": dirs})
    df["hhmm"]       = df["file_path"].apply(lambda x: x.split("/")[5])
    df["user"]        = df["file_path"].apply(lambda x: x.split("/")[6])
    df["request_id"]  = df["file_path"].apply(lambda x: x.split("/")[7])
    return df

Read the files for a specific request (replace the path with one from the listing above):

import json

# Replace with an actual path from the listing above
path = "/mount/fused-system/logs/2026-05-12/1430/user@example.com/abc123"

with open(f"{path}/metadata.json") as f:
    meta = json.load(f)

with open(f"{path}/stderr.log") as f:
    stderr = f.read()

print(meta["udf_name"], meta["execution_time_seconds"])
print(stderr or "no errors")

s3://fused-users/<org>/ — S3 home​

Your organization's S3 space. Use the File Explorer to browse it and confirm the exact paths for your account.

s3://fused-users/<org>/
├── {username}/
├── fused-system/
│   ├── checkpoints/
│   │   └── {user_email}/
│   │       └── {canvas_uuid}/
│   │           ├── <checkpoint_name>.json
│   │           └── {YYYY_MM_DD_HHMM}.json
│   ├── fused-cache/
│   │   └── {user_email}/
│   │       └── {udf_name}/
│   │           └── output/
│   │               └── {hash}/
│   ├── history/
│   │   └── {udf_uuid}/
│   │       └── {YYYY-MM-DD}/
│   │           └── {revision_uuid}/
│   │               └── {timestamp}.json
│   ├── integrations/
│   │   └── slack.json
│   ├── job-configs/
│   │   └── {YYYY-MM-DD}/
│   │       └── {job_uuid}/
│   │           └── file.json
│   └── logs/
│       └── {YYYY-MM-DD}/
│           └── {HHMM}/
│               └── {token_or_user}/
│                   └── {request_id}/

s3://fused-users/<org>/{username}/​

Your personal home directory for persistent storage. This is where you write output datasets, GeoTIFFs, and any files that need to be accessed outside of Fused. See Storage options for details.

@fused.udf(cache_max_age="0s")
def udf():
    import pandas as pd

    val = fused.api.list("s3://fused-users/<org>/<username>/")
    return pd.DataFrame(val, columns=["path"])

s3://fused-users/<org>/fused-system/​

Organization-wide system data managed by Fused. Contents are described below.

checkpoints/​

Canvas checkpoint snapshots created when you save a checkpoint in Workbench. Each canvas has its own directory under the user's email, containing timestamped JSON snapshots.

s3://fused-users/<org>/fused-system/checkpoints/
└── {user_email}/
    └── {canvas_uuid}/
        ├── <checkpoint_name>.json ← saved checkpoints, named by the user
        └── {YYYY_MM_DD_HHMM}.json ← auto-timestamped snapshots

See Canvas Checkpoints for how to create and restore them.

fused-cache/​

S3-backed output cache for @fused.cache. Stores results keyed by a hash of the function arguments, persisted per user and per UDF.

s3://fused-users/<org>/fused-system/fused-cache/
└── {user_email}/
    └── {udf_name}/
        └── output/
            └── {hash}/

history/​

Code history for every UDF in the organization. Each UDF is identified by its UUID; within that, every save is stored as a timestamped JSON snapshot grouped by day.

s3://fused-users/<org>/fused-system/history/
└── {udf_uuid}/
    └── {YYYY-MM-DD}/
        └── {revision_uuid}/
            └── {timestamp}.json    ← full UDF code snapshot at that point in time

integrations/​

Integration configuration files. For example, slack.json holds the Slack webhook configuration set up via Integrations & Secrets.

job-configs/​

Configuration files for batch jobs, stored by submission date and job UUID. Each job writes a file.json with its execution parameters.

s3://fused-users/<org>/fused-system/job-configs/
└── {YYYY-MM-DD}/
    └── {job_uuid}/
        └── file.json

logs/​

S3 mirror of the execution logs written to /mount/fused-system/logs/. Organized by the same date and time hierarchy, with one directory per request.

s3://fused-users/<org>/fused-system/logs/
└── {YYYY-MM-DD}/
    └── {HHMM}/
        └── {token_or_user}/
            └── {request_id}/
                ├── metadata.json
                ├── udf.json
                ├── stdout.log
                └── stderr.log

List available dates:

import fused
fused.api.list("s3://fused-users/<org>/fused-system/logs/")

See also​