Register a source
Define the source in a service provider. Always scope access to the intended workspace and principal. Do not use an unconditional allow callback in a multi-tenant application.studio.sources.sync. The source callback adds a further restriction; it cannot bypass workspace authorization. Register callbacks in a provider rather than a cached PHP configuration file.
Install the latest Studio migrations before using the commands.
Create an inventory
Resume a large S3 inventory
S3 listing saves progress after each page of up to 1,000 objects. By default, one command handles at most 100 pages. Choose a smaller batch when running scheduled commands:--resume until it reports Inventory ready:
.partial, .checkpoint and .lock sidecar files in place while scanning. An interrupted page is discarded on resume and fetched again. Completed pages are not listed again. Only one process can advance a given output at a time, and authorization is checked before and after every storage page. No worker is required; a scheduler may run the command repeatedly. --pages accepts 1–1,000.
The encrypted checkpoint belongs to the initiating workspace, principal, mount revision and storage configuration. Use the same Laravel encryption key when resuming. If the source configuration changes or the provider expires its continuation token, choose a new output and create a fresh inventory. An S3 listing is not a frozen snapshot of a changing bucket: schedule another inventory to reconcile later additions. This workflow does not infer deletions.
You can also supply your own UTF-8 JSONL inventory, with one object path per line:
Inspect before importing
Import and resume
inspected, imported and nextCursor. Repeat with the returned cursor until it is null:
Manage imports in Settings
After preparing an inventory, register its private local path on the source in your provider:Browsing and access
The source appears as a read-only root folder. Folder navigation, search/filtering, selection and content delivery use the existing Studio interface. Files without a registered thumbnail show a type icon; opening the file can use its original. Import itself does not generate derivatives or copy source thumbnails. You can explicitly enable and run image conversion as described below. Source access is checked again when resolving indexed items and opening originals. Disabling a mount, changing its disk/prefix/revision or denying its authorization callback blocks the affected source. Reimport after a source configuration change. Before serving an original, Studio compares its size and modification timestamp with the index. Changed or missing objects are unavailable until reimported. This is not a cryptographic content check: an external system that overwrites the same path with the same size and timestamp needs immutable object keys or a future version-aware adapter. Historical indexed versions of mutable disk paths cannot be opened as preserved snapshots.Generate thumbnails for imported images
Enable Studio-owned image conversions separately for each trusted source:--after=NEXT_CURSOR printed by the command. Non-image entries, inaccessible sources and sources without conversion opt-in are skipped. A queue connection requires its worker; the sync connection performs processing during the explicit command instead. Browsing the library never starts conversions. The initiating principal needs the relevant studio.files.optimize and studio.files.process permissions as well as source access.
By default, generated variants are written to the workspace’s Studio disk. A named profile may explicitly select another output disk. Originals stay at their external paths and are never removed by Studio’s original-retention setting. Refresh variants using --refresh --retention=keep or --refresh --retention=prune; pruning applies to replaced Studio-owned derivatives, not source originals. See Image conversions for profiles and cleanup.
The worker checks the indexed source before processing and again before publishing variants. If the file changes, reimport the source before regenerating. These checks compare size and modification time; they do not make mutable external paths into cryptographically immutable snapshots. Revoking source access also blocks delivery of generated variants.