5. Working with Files

This is part 5 of the Your First Plugin tutorial. Make sure you’ve completed 4. Use Integration in Node first.

Plugins can read and create files. Since plugins run in isolated processes, file I/O goes through the platform’s file helper — the SDK handles all the bridging transparently.

Reading files

Add a node that reads a file input: A File flows through a V2 node like any other value: declare a bindable File config field to receive one, and a File-typed output field to emit one.

from noxus_sdk.files import File
from noxus_sdk.nodes.base import BaseNodeV2, NodeConfiguration, NodeOutputs
from noxus_sdk.nodes.types import NodeCategory
from noxus_sdk.ncl import ConfigFile, Parameter
from noxus_sdk.plugins.context import RemoteExecutionContext


class ParseWeatherFileConfig(NodeConfiguration):
    file: File = Parameter(bindable=True, display=ConfigFile(label="Cities File"))


class ParseWeatherFileOutputs(NodeOutputs):
    cities: list[str]


class ParseWeatherFileNode(BaseNodeV2[ParseWeatherFileConfig, ParseWeatherFileOutputs]):
    node_name = "ParseWeatherFileNode"
    title = "Parse Weather File"
    description = "Reads a CSV file of cities and returns weather data"
    category = NodeCategory.DATA
    color = "#4A90E2"

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        # The bindable File input is read from self.config.
        file = self.config.file

        # Read file content through the file helper.
        content = await file.get_content(ctx)
        text = content.decode("utf-8")

        # Parse CSV lines.
        cities = [line.strip() for line in text.splitlines() if line.strip()]

        return {"cities": cities}

How file reading works

When a File type input arrives, it contains metadata (name, URI, content type) but not the actual bytes. Calling file.get_content(ctx) triggers: Your plugin runs inside a sandbox with no direct access to platform storage, so the SDK asks the platform for the bytes over the same channel the platform used to call your node. The platform only serves files belonging to the workspace the run is executing for — a plugin cannot reach another workspace’s files. You can also access file metadata without downloading:

file.name          # "cities.csv"
file.content_type  # "text/csv"
file.uri           # "spot://..."
file.id            # UUID string

Creating files

from noxus_sdk.ncl import ConfigBigText, Parameter


class GenerateReportConfig(NodeConfiguration):
    report_text: str = Parameter(
        default="", bindable=True, display=ConfigBigText(label="Report Text"),
    )


class GenerateReportOutputs(NodeOutputs):
    report_file: File


class GenerateReportNode(BaseNodeV2[GenerateReportConfig, GenerateReportOutputs]):
    node_name = "GenerateReportNode"
    title = "Generate Weather Report"
    description = "Creates a text file with weather data"
    category = NodeCategory.DATA
    color = "#4A90E2"

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        # Create a file through the file helper.
        report_file = await File.from_bytes(
            ctx,
            self.config.report_text.encode("utf-8"),
            name="weather_report.txt",
            content_type="text/plain",
        )

        return {"report_file": report_file}

File.from_bytes() uploads the content to the platform’s storage and returns a File object that downstream nodes can use. File.from_bytes_internal_uri() is an alias with a self-documenting name — reach for it at explicit persistence sites (e.g. saving a downloaded attachment) when you want the call to read clearly.

Giving a library real file paths

Some libraries need a real path on disk rather than a File reference. Download inputs into the sandbox’s local filesystem with persist_files_locally:

from noxus_sdk.files import persist_files_locally


# self.config.files is a bindable `list[File]` input on the node's config schema.
async def call(self, ctx: RemoteExecutionContext) -> dict:
    # Writes each File's bytes under a local dir and returns the dir path.
    folder = await persist_files_locally(ctx, self.config.files)
    # ... hand `folder` to a library that wants paths, then upload results back
    return {"folder": folder}

The directory lives on the plugin’s own sandbox disk (default: a fresh dir under /tmp); it is not platform storage. To hand results back to the flow, upload them again with File.from_bytes.

Quick reference

Operation	Code
Read file content	`content = await file.get_content(ctx)`
Create from bytes	`await File.from_bytes(ctx, b"...", name="file.txt")`
Create from text	`await File.from_bytes(ctx, text.encode("utf-8"), name="out.txt", content_type="text/plain")`
Create (explicit persistence site)	`await File.from_bytes_internal_uri(ctx, data, name="attachment.pdf")`
Download inputs to local disk	`path = await persist_files_locally(ctx, files)`
Access file name	`file.name`
Access content type	`file.content_type`
Access file URI	`file.uri`
File input (V2)	bindable `File` config field: `Parameter(bindable=True, display=ConfigFile(label=...))`
File output (V2)	a `File`-typed field on the `NodeOutputs` schema
File list (V2)	`list[File]` annotation (bindable input or output field)

data, name, and content_type are positional/keyword on File.from_bytes(ctx, data, name=..., content_type=...) — data is the first argument after ctx, not a keyword-only field. (On a V1 node these are declared instead with TypeDefinition(data_type=DataType.File) connectors.)

Handling multiple files

Use a list[File] field to receive or produce multiple files. On a V2 node it’s a bindable list[File] config field (input) and/or a list[File] output field:

class MergeFilesConfig(NodeConfiguration):
    files: list[File] = Parameter(
        default_factory=list, bindable=True, display=ConfigFileArray(label="Input Files"),
    )


class MergeFilesOutputs(NodeOutputs):
    combined_text: str


class MergeFilesNode(BaseNodeV2[MergeFilesConfig, MergeFilesOutputs]):
    node_name = "MergeFilesNode"
    title = "Merge Files"
    description = "Concatenates the text of several files"

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        all_text = []
        for f in self.config.files:
            content = await f.get_content(ctx)
            all_text.append(content.decode("utf-8"))

        return {"combined_text": "\n---\n".join(all_text)}

Parsing email

If your node receives raw email bytes, the SDK’s Email helper parses an RFC-822 message into a typed model whose attachments and inline images are persisted to platform storage as Files — over the same host callbacks, so it never needs network access back to the platform:

import email

from noxus_sdk.email import Email
from noxus_sdk.errors import IntegrationFailedError


# self.config.raw is a bindable `File` input carrying the raw .eml bytes.
async def call(self, ctx: RemoteExecutionContext) -> dict:
    data = await self.config.raw.get_content(ctx)
    msg = email.message_from_bytes(data, policy=email.policy.default)

    parsed = await Email.from_email_object(ctx, msg)
    if not parsed.attachments:
        raise IntegrationFailedError("Email had no attachments to process")

    # .to_text() renders subject/body for LLM or tool input;
    # parsed.attachments are File refs already saved to storage.
    return {"text": parsed.to_text(), "files": parsed.attachments}

Pass zip_attachments=True to Email.from_email_object to collapse all attachments into a single attachments.zip file instead of one File per part.

Next: Advanced Techniques →

Config UI controls, dynamic config, list handling, error handling, and deployment.

Overview

Tutorial

Reference

GitOps

Reading files

How file reading works

Creating files

Giving a library real file paths

Quick reference

Handling multiple files

Parsing email

Next: Advanced Techniques →

​Reading files

​How file reading works

​Creating files

​Giving a library real file paths

​Quick reference

​Handling multiple files

​Parsing email

Next: Advanced Techniques →

Reading files

How file reading works

Creating files

Giving a library real file paths

Quick reference

Handling multiple files

Parsing email