Using Platform Resources

Your plugin code runs inside an isolated sandbox worker, not in a platform process. It has no route back to internal platform addresses and holds no platform credential. Everything it needs from the platform is handed to it through one object: the RemoteExecutionContext (ctx) passed to every call and poll. File and platform access happen as JSON-RPC callbacks on the worker’s own channel, which the platform services in-process against its database and storage — so no key ever enters the sandbox.

There is no context.models, context.artifacts, or HTTP-to-platform surface inside a plugin. The sandbox surface is exactly what’s on RemoteExecutionContext below: files, integration credentials, plugin config, and the group id.

The execution context

Import it from noxus_sdk.plugins.context. Every node’s call(self, ctx, ...) and every trigger’s poll(self, ctx, state) receives one.

Attribute / method	Type	Description
`ctx.group_id`	`str \| None`	The tenant/workspace (group) id for this call.
`ctx.plugin_config`	`dict`	The plugin-level config values (see Configurable Plugins).
`ctx.integration_credentials`	`dict[str, dict]`	Credentials the platform injected, keyed by integration type.
`ctx.get_integration_credentials(type)`	`-> dict`	Safe accessor for one integration’s credentials (`{}` if absent).
`ctx.get_file_helper()`	`-> FileHelper`	File I/O over host callbacks (download / upload).
`ctx.call_token`	`str \| None`	Opaque, single-use token the host uses to scope callbacks. Plugin code never reads or sets it.

from noxus_sdk.plugins.context import RemoteExecutionContext

async def call(self, ctx: RemoteExecutionContext, url: str) -> dict:
    creds = ctx.get_integration_credentials("my_service")   # per-workspace secrets
    timeout = ctx.plugin_config.get("api_timeout", 30)      # plugin-level config
    api_key = creds.get("api_key", "")
    ...

Files — host callbacks, no egress

A File input arrives as a File model; return a File (or list[File]) to emit one. Reading or writing a file’s bytes issues a JSON-RPC callback (host.get_content / host.upload_file) on the worker channel. The platform services these in-process, scoped by the single-use call token to the calling workspace — a plugin cannot read or plant files in another tenant. Use the file helper directly, or the higher-level File helpers that wrap it:

from noxus_sdk.files import File, persist_files_locally

async def call(self, ctx: RemoteExecutionContext, raw: File) -> dict:
    # Download an input File's bytes
    data = await raw.get_content(ctx)

    # Persist derived bytes and return a File output
    out = await File.from_bytes(
        ctx, data, name="processed.csv", content_type="text/csv"
    )

    # When a library needs real paths on disk rather than File refs
    folder = await persist_files_locally(ctx, [raw])

    return {"file": out}

The lower-level helper (ctx.get_file_helper()) exposes get_content(file) and upload_file(file_name=, content=, content_type=, group_id=) if you need them, but File.from_bytes(...) / raw.get_content(ctx) cover the common cases.

noxus plugin serve (local dev) has no host to service file callbacks, so file operations raise there. Nodes that read or write platform files can only be exercised under the platform runtime.

Email

noxus_sdk.email.Email parses a raw email into a typed object with a markdown body and its attachments/inline images persisted as Files.

import email
from noxus_sdk.email import Email

async def call(self, ctx: RemoteExecutionContext, raw: File) -> dict:
    msg = email.message_from_bytes(await raw.get_content(ctx), policy=email.policy.default)
    parsed = await Email.from_email_object(ctx, msg)
    return {"text": parsed.to_text(), "files": parsed.attachments}

.to_text() renders the email for LLM/tool input; pass zip_attachments=True to collapse attachments into a single zip.

Integration credentials

Credentials are the one per-workspace part of the plugin model — each workspace connects its own. A node declares which integration types it needs and reads them from the context at run time. See Creating Integrations for the full authoring flow.

class GetWeatherNode(BaseNode[EmptyConfig]):
    integrations = {"my_weather": ["api_key"]}   # platform injects a credential picker

    async def call(self, ctx: RemoteExecutionContext, city: str) -> dict:
        creds = ctx.get_integration_credentials("my_weather")
        return {"used_key": creds.get("api_key", "MISSING")}

Typed errors

Raise IntegrationFailedError or UnexpectedError from noxus_sdk.errors — not a bare Exception — when an upstream API or credential fails; the message reaches the node’s failure UI.

from noxus_sdk.errors import IntegrationFailedError

if not ctx.get_integration_credentials("my_service").get("api_key"):
    raise IntegrationFailedError("No API key connected — connect the integration.")

The exception type does not cross the sandbox boundary today — only the message does. Make messages actionable, since that string is all the user sees.

Best Practices

Files

Treat file access as I/O over the callback channel. Return File outputs rather than raw bytes so the platform tracks storage and lineage. Use File.from_bytes for derived content and persist_files_locally only when a library truly needs a filesystem path.

Credentials

Read credentials from ctx.get_integration_credentials(type) at call time — never cache them across calls, since they are per-workspace and can change. Fail with IntegrationFailedError when a required credential is missing.

Context usage

Pass only what a node needs. ctx.group_id scopes work to the current workspace; do not attempt to reach other groups — the call token overrides any group_id you pass to a callback anyway.

Failure handling

Degrade for expected external flakiness (return an empty typed result), and reserve raised errors for genuine misconfiguration. A raised exception fails the whole run.

Creating Integrations

Build typed credentials and connect nodes to external systems.

Overview

Tutorial

Reference

GitOps

The execution context

Files — host callbacks, no egress

Email

Integration credentials

Typed errors

Best Practices

Creating Integrations

​The execution context

​Files — host callbacks, no egress

​Email

​Integration credentials

​Typed errors

​Best Practices

Creating Integrations

The execution context

Files — host callbacks, no egress

Email

Integration credentials

Typed errors

Best Practices