What are Runtimes?
Runtimes are secure, isolated execution environments that power Reactors and Proxy Transforms, allowing your custom code to process sensitive data without it touching your systems.
Supported Runtime Images
Basis Theory supports the following runtime images, each with different capabilities:
| Feature | node-bt | node22 |
|---|---|---|
| Node.js Version | 16 | 22 |
| Provisioning | Synchronous | Asynchronous |
| Dependencies | Whitelist only | Any npm package |
| Timeout | Fixed | Configurable |
| Resources | Fixed | Scalable |
| Warm Instances | Default only | Configurable |
| Permissions | Via linked Application | Declarative |
node-bt
The node-bt runtime image is the default runtime with a curated set of whitelisted dependencies. This runtime is used when no runtime object is specified.
Best for:
- Existing reactor code
- Use cases covered by available dependencies
- Simple integrations
node22
The node22 runtime image provides full control over your runtime environment, allowing you to install any npm package and configure compute resources. To use this runtime, specify runtime.image: "node22" when creating your reactor or proxy transform.
Best for:
- New reactor projects
- Custom dependency requirements
- Performance-critical workloads
- Advanced error handling needs
Choosing a Runtime
| Scenario | Recommended Runtime Image |
|---|---|
| New projects | node22 for maximum flexibility |
| Existing code | node-bt continues to work; migrate when needed |
| Custom dependencies | node22 if you need packages not in the whitelist |
| Configurable resources | node22 for timeout, memory, and concurrency control |