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/sdk

import { 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';

Agent SDK

Autonomous agents that can dispatch serverless workloads

AI Monitoring

Track costs and tokens for AI calls in serverless functions

Cluster

Multi-node orchestration for distributed workloads