Serverpod File Uploads
Developmentserverpod-file-uploadsServerpod File Uploads is an Agent Skill for development published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
File uploads in Serverpod — upload descriptions, verification, storage backends (database, S3, GCP). Use when implementing file uploads or cloud storage.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-file-uploads/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/serverpod-file-uploads, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Serverpod File Uploads
Flow: server issues upload description → client uploads → server verifies. Default storage is the database; use S3, GCP, R2, or compatible object storage for production.
Server: create upload description
Future<String?> getUploadDescription(Session session, String path) async {
return await session.storage.createDirectFileUploadDescription(
storageId: 'public',
path: path,
);
}
Always authorize the request and derive the path from trusted server-side state (user id, tenant id, object id). Do not accept arbitrary client paths.
Server: verify upload
Future<bool> verifyUpload(Session session, String path) async {
return await session.storage.verifyDirectFileUpload(
storageId: 'public', path: path);
}
Always verify after client upload when using object storage.
Client: upload
var desc = await client.myEndpoint.getUploadDescription('profile/$userId/avatar.png');
if (desc != null) {
var uploader = FileUploader(desc);
await uploader.upload(byteDataOrStream);
await client.myEndpoint.verifyUpload('profile/$userId/avatar.png');
}
Use Stream for large files. Paths: no leading slash, object-store compatible, normalized, and scoped to the authenticated user/tenant.
Security checklist
- Require authentication/authorization for both description and verification endpoints.
- Validate or derive content type, size, and extension before issuing descriptions.
- Never let clients choose cross-tenant paths or storage IDs.
- Store metadata in your database after
verifyDirectFileUploadsucceeds.
Accessing stored files
session.storage.fileExists(storageId: 'public', path: path)session.storage.getPublicUrl(storageId: 'public', path: path)(public storage only)session.storage.retrieveFile(storageId: 'public', path: path)
Storage backends
- Database (default):
publicandprivatestorages. Fine for dev. - Google Cloud Storage: Add
serverpod_cloud_storage_gcp, set HMAC keys inpasswords.yamlor env. Register:pod.addCloudStorage(GoogleCloudStorage(...)). - AWS S3: Add
serverpod_cloud_storage_s3, set AWS keys. Register:pod.addCloudStorage(S3CloudStorage(...)). - S3-compatible/R2: Use the matching integration package when targeting compatible providers.
Use storageId: 'public' or 'private' when replacing defaults.