n8n-nodes-modal-sandbox

Custom n8n nodes for managing Modal Sandboxes using credentials stored in n8n. This is a community package; it is not an official n8n or Modal integration, and has not been verified by n8n.

Nodes

• Modal Sandbox (modalSandbox): one of create, exec, read_text, write_text, status, terminate for one incoming JSON item.
• Modal Sandbox Preflight (modalSandboxPreflight): explicit, read-only SDK/credential check using sandboxes.list.

Both require an n8n Modal API credential containing a Modal Token ID and Token Secret. Credentials are obtained through n8n's credential manager and passed explicitly to the Modal JavaScript SDK. Do not put token values in workflow data.

Configuration

In the Modal Sandbox node, configure:

• Managed Sandbox Service Tag: an exact tag value chosen for your deployment. Each new Sandbox receives service: <your value>, and every subsequent operation verifies the same current server-side tag before proceeding. A tag is a scope marker, not an authentication boundary: account administrators with tagging rights can deliberately assign the tag.
• Modal App Name: the Modal App used to create Sandboxes.

Both settings are required and belong to the node configuration, not to caller-controlled operation inputs. There are no built-in service tags, App IDs, endpoint URLs, webhook IDs, credentials, or personal deployment identifiers in the runtime package.

The adapter expects one JSON item with fields operation, sandbox_id, image, argv_json, workdir, timeout_ms, idle_timeout_ms, cpu, memory_mib, path, content, and env_json, as applicable. Inputs are validated; command arguments use a JSON array (there is no implicit shell). Process stdin is closed with EOF. Results and truncation flags are returned in JSON.

Security and limitations

• exec can execute arbitrary programs; write_text can overwrite files; terminate irreversibly ends a Sandbox. Restrict who can run this workflow and protect any MCP endpoint exposing these operations. Do not expose a public unauthenticated tool endpoint.
• Preflight performs one authenticated listing read; it does not create or terminate a Sandbox. Its node does not automatically run as a credential test.
• The service tag restricts the operations to a selected set of Sandboxes but is not proof of origin or an account permission mechanism.
• Text reads are bounded but not atomic; a file can change between metadata inspection and reading. Avoid concurrent modification of files being read.
• n8n task-runner timeouts are separate from SDK, workflow, and MCP-client deadlines. Verify effective deployment timeouts independently.
• Raw Modal SDK errors can contain operational data; the package redacts the exact selected credential values from messages before limiting returned text. This cannot prevent all possible indirect or encoded disclosure.

Installation

Install on a compatible self-hosted n8n instance following n8n's community-node installation instructions. The package has a runtime dependency on modal@0.11.0 and requires network access from the n8n node execution environment to reach Modal.

npm install n8n-nodes-modal-sandbox

This command is intended for the n8n instance's supported community-node installation context, not the Code node. Restart or reload nodes as required by your deployment procedure, then select a Modal API credential on each node. Do not paste credentials into commands or logs.

Development

In the source repository, without invoking real Modal operations:

npm run check
npm test
npm pack --dry-run

The included development tests use a simulated n8n context and a local Modal SDK double. They do not establish native n8n loading, successful live authentication, or end-to-end Sandbox acceptance.

License

UNLICENSED — no license grant is provided by this package. Use and redistribution may be restricted. The package's visibility on npm does not grant rights beyond applicable law.