Run AI workloads in the cloud with hybrid execution, sandboxes, and built-in governance.
Serverless SDK
The Serverless SDK lets you define functions that run locally during development and in the cloud in production. It provides a Modal-like API with hybrid execution backends, interactive sandboxes, persistent volumes, and built-in governance via Grace policies.
npm install @codmir/sdkimport { app, fn } from '@codmir/sdk/serverless';Quick Start
import { app, fn } from '@codmir/sdk/serverless';
const myApp = app({ name: 'data-pipeline' });
const processData = fn(myApp, {
cpu: 2,
memory: '4GB',
timeout: 300,
})(async (data: string) => {
// Your code runs in the cloud
return data.toUpperCase();
});
// Local development
const localResult = await processData.local('test data');
// Cloud execution
const remoteResult = await processData.remote('real data');
// Auto-select based on environment
const result = await processData.call('auto data');Apps
An app is a container that groups functions, sandboxes, and configuration together.
import { CodmirApp, createApp } from '@codmir/sdk/serverless';
const app = new CodmirApp({
name: 'my-app',
image: 'python:3.11',
secrets: ['OPENAI_API_KEY'],
volumes: { '/data': 'my-volume' },
grace: {
enabled: true,
preferGreen: true,
},
});App Config
| Option | Type | Description |
|---|---|---|
name | string | Unique app identifier |
image | string | Default container image for all functions |
secrets | string[] | Secrets injected into all functions |
volumes | Record<string, string> | Default volume mounts |
grace | GraceConfig | Governance configuration |
Functions
Functions are the core execution unit. Define them with resource requirements and a handler.
const embed = app.function({
cpu: 4,
memory: '8GB',
gpu: 'T4',
timeout: 600,
retries: 2,
pool: 'auto',
})(async (texts: string[]) => {
// Runs with 4 CPUs, 8GB RAM, and a T4 GPU
return await generateEmbeddings(texts);
});Local vs Remote Execution
// Always runs locally (for development/testing)
const result = await embed.local(['hello', 'world']);
// Always runs in the cloud
const result = await embed.remote(['hello', 'world']);
// Auto-selects based on NODE_ENV
const result = await embed.call(['hello', 'world']);Function Config
| Option | Type | Default | Description |
|---|---|---|---|
cpu | number | 1 | CPU cores |
memory | number | string | '256MB' | RAM allocation |
gpu | boolean | string | false | GPU type: 'T4', 'A10G', 'A100', 'H100' |
timeout | number | 300 | Max execution time in seconds |
retries | number | 0 | Retry count on failure |
concurrencyLimit | number | — | Max concurrent executions |
pool | ExecutionPool | 'auto' | Preferred execution backend |
image | string | App default | Container image |
secrets | string[] | [] | Secrets to inject |
volumes | Record | {} | Volume mounts |
env | Record | {} | Environment variables |
checkpoints | boolean | false | Enable checkpointing for long tasks |
schedule | string | — | Cron expression for scheduled runs |
Sandboxes
Sandboxes are interactive cloud environments for running commands, reading/writing files, and iterating on code.
const sandbox = app.sandbox({ image: 'python:3.11' });
await sandbox.spawn();
// Execute commands
await sandbox.exec('pip install numpy pandas');
const result = await sandbox.exec('python script.py');
console.log(result.stdout);
// Read and write files
await sandbox.writeFile('/app/data.json', JSON.stringify(data));
const content = await sandbox.readFile('/app/output.json');
// Clean up
await sandbox.terminate();Sandbox Config
| Option | Type | Description |
|---|---|---|
image | string | Base container image (required) |
cpu | number | CPU cores |
memory | number | string | RAM allocation |
gpu | boolean | string | GPU type |
timeout | number | Max lifetime in seconds (default: 3600) |
workdir | string | Working directory inside the container |
env | Record | Environment variables |
secrets | string[] | Secrets to inject |
volumes | Record | Volume mounts |
webAccess | boolean | Enable web access via tunnel |
Custom Images
Build custom container images with pre-installed dependencies.
import { createImage } from '@codmir/sdk/serverless';
const mlImage = createImage({
base: 'python:3.11-slim',
pythonPackages: ['torch', 'transformers', 'numpy'],
systemPackages: ['ffmpeg', 'libsndfile1'],
runCommands: ['python -c "import torch; print(torch.__version__)"'],
copyFiles: [{ from: './models', to: '/app/models' }],
env: { TRANSFORMERS_CACHE: '/app/cache' },
workdir: '/app',
});Volumes
Persistent storage that survives across function executions.
import { createVolume } from '@codmir/sdk/serverless';
const dataVol = createVolume({
name: 'training-data',
size: 100, // GB
region: 'us-east-1',
});
// Mount in a function
const train = fn(myApp, {
gpu: 'A100',
volumes: { '/data': 'training-data' },
})(async () => {
// /data persists between runs
});Secrets
Securely inject credentials into function environments.
import { createSecret } from '@codmir/sdk/serverless';
const apiKey = createSecret({
name: 'OPENAI_API_KEY',
envVar: 'OPENAI_API_KEY',
});
const generate = fn(myApp, {
secrets: ['OPENAI_API_KEY'],
})(async (prompt: string) => {
// process.env.OPENAI_API_KEY is available
});Decorator API
The decorator-style API provides a Modal-like syntax for defining serverless resources.
import { app, fn, web_endpoint, cron, method } from '@codmir/sdk/serverless';
const myApp = app({ name: 'my-service' });
// Basic function
const process = fn(myApp, { cpu: 2 })(async (data: string) => {
return data.toUpperCase();
});
// Web endpoint
const api = web_endpoint(myApp, { method: 'POST' })(async (req) => {
return { status: 'ok', data: req.body };
});
// Scheduled function (cron)
const dailyReport = cron(myApp, '0 9 * * *')(async () => {
await generateDailyReport();
});Class Methods
class DataProcessor {
@method(myApp, { cpu: 4, memory: '8GB' })
async process(data: string) {
return data.toUpperCase();
}
}Execution Layer
For programmatic control over execution, use the lower-level execution functions.
import { execute, executeAsync, executeLocal } from '@codmir/sdk/serverless';Execution Results
Every execution returns an ExecutionResult with metrics and status.
interface ExecutionResult<T> {
id: string;
status: ExecutionStatus;
result?: T;
error?: string;
metrics: {
durationMs: number;
queuedMs?: number;
coldStartMs?: number;
cpuUsage?: number;
memoryUsageMb?: number;
creditsUsed: number;
carbonFootprint?: number; // gCO2e
pool: ExecutionPool;
};
logs?: string[];
artifacts?: ExecutionArtifact[];
checkpoint?: unknown;
}Execution Pools
Functions can run on different backends depending on cost, latency, and availability needs.
| Pool | Description |
|---|---|
auto | Automatically selects the best pool (default) |
modal | Modal.com infrastructure |
fargate | AWS Fargate containers |
github | GitHub Actions runners |
community | Community-contributed compute |
local | Local machine |
Streaming and Progress
import { logs, progress, checkpoint } from '@codmir/sdk/serverless';Track long-running executions with progress callbacks, log streaming, and checkpointing for resumable tasks.
Grace Governance
Every app and function can be configured with Grace policies for ethical execution governance.
const app = new CodmirApp({
name: 'sensitive-pipeline',
grace: {
enabled: true,
requireApproval: true,
maxBudget: 100, // Max credits per execution
preferGreen: true, // Route to low-carbon compute
impactCategory: 'medium',
},
});| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable Grace policy enforcement |
requireApproval | boolean | false | Require human approval before execution |
maxBudget | number | — | Maximum credits per execution |
preferGreen | boolean | false | Prefer low-carbon compute regions |
impactCategory | string | 'safe' | Ethical impact level: safe, low, medium, high |
TypeScript Support
import type {
AppConfig,
FunctionConfig,
SandboxConfig,
ImageConfig,
VolumeConfig,
SecretConfig,
ExecutionResult,
ExecutionStatus,
ExecutionPool,
ResourceSpec,
GraceConfig,
CallOptions,
StreamEvent,
BatchConfig,
BatchResult,
} from '@codmir/sdk/serverless';