Factorial Code Storage

Factorial Code Storage is a robust file storage system designed to handle file operations within your processes. It provides a simple and efficient way to store, retrieve, and manage files through accessible source code integration.

With Factorial Code Storage, you can perform various file operations including:

• File Upload: Store files from your processes or external sources
• Automatic Form Uploads: Receive files submitted from input-parameter forms directly in storage
• File Download: Retrieve files for processing or analysis
• File Management: List and delete your stored files
• Signed URLs: Generate temporary download URLs for existing files

Use Cases

Factorial Code Storage is perfect for scenarios such as:

• Document Processing: Store uploaded documents for analysis or transformation
• Image Processing: Handle image files for resizing, conversion or analysis
• Data Export: Generate and store reports, CSV files or other exports
• File Sharing: Create temporary file storage for sharing between processes
• Backup Operations: Store important files as part of backup workflows

Note

Each Factorial Code plan has different storage limits. For information see our plans and limits page.

Automatic Uploads from Input Parameter Forms

When your process uses an input parameter form with file fields ("ui:widget": "file"), Factorial Code uploads those submitted files to storage automatically before execution starts.

Inside your process code, file parameters become storage references you can use with fcode.storage.download() and other storage methods.

For one file field, you receive one storage path. If your form allows multiple files, you will receive an array of storage paths.

JavaScript

Download a file submitted through a form

const {
  context: { parameters },
} = fcode;

const uploadedPath = parameters.inputFile;
// Upload path starts with "fcode.storage://"
const fileStream = await fcode.storage.download(uploadedPath.replace("fcode.storage://", ""));

Python

Download a file submitted through a form

uploaded_path = fcode.context.parameters.get("inputFile")
# Upload path starts with "fcode.storage://"
content = fcode.storage.download(uploaded_path.replace("fcode.storage://", ""))

Tip

This behavior lets your form integrations handle large files without passing raw browser payloads through your process parameters.

Access Methods

Factorial Code Storage can be accessed through multiple methods, making it flexible for different use cases and integration scenarios:

1. From Process Source Code

The most direct way to use Factorial Code Storage is from within your process source code using the fcode.storage helper:

JavaScript

Uploading a file

const path = require("node:path");
const localPath = path.join(process.env.TMP_DATA_DIR, "myfile.txt");
await fcode.storage.upload("path/myfile.txt", fs.createReadStream(localPath));

Listing files

const files = await fcode.storage.list();
console.log(files);

Downloading a file

const path = require("node:path");
const localPath = path.join(process.env.TMP_DATA_DIR, "downloaded.txt");
const stream = await fcode.storage.download("path/myfile.txt");
stream.pipe(fs.createWriteStream(localPath));

Deleting a file

await fcode.storage.delete("path/myfile.txt");

Creating a signed URL

const signed = await fcode.storage.createSignedUrl("path/myfile.txt");
console.log(signed.url, signed.expiresAt);

const signedWithCustomExpiry = await fcode.storage.createSignedUrl("path/myfile.txt", {
  expiresInSeconds: 900,
});
console.log(signedWithCustomExpiry.url, signedWithCustomExpiry.expiresAt);

Python

Uploading a file

import os
local_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "myfile.txt")
with open(local_path, "rb") as f:
    obj = fcode.storage.upload("path/myfile.txt", f)
    print("Uploaded:", obj.name, obj.size, obj.link)

Listing files

objects = fcode.storage.list()
for obj in objects:
    print(obj.name, obj.size, obj.link)

Downloading a file

import os
local_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "downloaded.txt")
content = fcode.storage.download("path/myfile.txt")
with open(local_path, "wb") as f:
    f.write(content)

Deleting a file

fcode.storage.delete("myfile.txt")

Creating a signed URL

signed = fcode.storage.create_signed_url("path/myfile.txt")
print(signed.url, signed.expires_at)

signed_custom = fcode.storage.create_signed_url(
    "path/myfile.txt",
    expires_in_seconds=900
)
print(signed_custom.url, signed_custom.expires_at)

2. From External Systems via REST API

Factorial Code Storage is also available through our REST API, allowing you to upload, download, list, delete, and create signed URLs from any external system. This enables integration with third-party applications, web services, or any system that can make HTTP requests.

3. Using Factorial Code Run SDK

You can interact with Factorial Code Storage from external applications using our Factorial Code Run SDK, available for both JavaScript and Python:

JavaScript

Using Factorial Code Run SDK for JavaScript

const { FcodeStorage } = require('@factorialco/fcode-sdk');
const fs = require('fs');

const storage = new FcodeStorage({ apiToken: 'your-api-token' });

// Upload a file (using Node.js stream)
await storage.upload('path/myfile.txt', fs.createReadStream('./myfile.txt'));

// List files
const files = await storage.list();
console.log(files);

// Download a file
const stream = await storage.download('path/myfile.txt');
stream.pipe(fs.createWriteStream('./downloaded.txt'));

// Delete a file
await storage.delete('myfile.txt');

// Create a temporary signed URL (default expiration ~1 hour)
const signed = await storage.createSignedUrl('path/myfile.txt');
console.log(signed.url, signed.expiresAt);

// Custom expiration
const signedWithCustomExpiry = await storage.createSignedUrl('path/myfile.txt', {
  expiresInSeconds: 900,
});
console.log(signedWithCustomExpiry.url, signedWithCustomExpiry.expiresAt);

Install the SDK: pnpm install @factorialco/fcode-sdk

Python

Using Factorial Code Run SDK for Python

from fcode_sdk import FcodeStorage, FcodeApiConfig

storage = FcodeStorage(
    FcodeApiConfig(api_token='your-api-token')
)

# Upload a file
with open('myfile.txt', 'rb') as f:
    obj = storage.upload('myfile.txt', f)
    print('Uploaded:', obj.name, obj.size, obj.link)

# List all storage objects
objects = storage.list()
for obj in objects:
    print(obj.name, obj.size, obj.link)

# Download a file
content = storage.download('myfile.txt')
with open('downloaded.txt', 'wb') as f:
    f.write(content)

# Delete a file
storage.delete('myfile.txt')

# Create a temporary signed URL (default expiration ~1 hour)
signed = storage.create_signed_url('path/myfile.txt')
print(signed.url, signed.expires_at)

# Custom expiration
signed_custom = storage.create_signed_url(
    'path/myfile.txt',
    expires_in_seconds=900
)
print(signed_custom.url, signed_custom.expires_at)

Install the SDK: pip install factorial-fcode-sdk

4. From AI Agents via MCP Server

Factorial Code Storage is available as MCP (Model Context Protocol) tools in our MCP server, making it incredibly powerful when combined with AI agents. This enables AI agents to:

• Handle file-based tasks end-to-end without manual intervention
• Process complex data using the full power of Python/JavaScript ecosystems
• Store and retrieve results securely in the cloud
• Chain multiple operations across different files and datasets

When combined with our run_code tool, AI agents can upload files, generate and execute code to process them, and store results back to Factorial Code Storage automatically.

Tip

The combination of Factorial Code Storage + MCP tools + run_code creates a powerful environment where AI agents can handle complex file processing workflows autonomously.

Working with Local Disk

Factorial Code Storage works seamlessly with local disk for comprehensive file handling workflows. This combination is particularly useful when you need to:

• Process files that require specific file paths or libraries that don’t support streams
• Perform complex data transformations that benefit from local file access
• Handle large files that need to be processed in chunks