Adding a new Provider

This guide explains how to add a new provider for ComputeSDK by implementing the required interfaces and methods.

Basic Provider Structure

import { createProvider } from 'computesdk'
import type { 
  Runtime, 
  ExecutionResult, 
  SandboxInfo,
  RunCommandOptions,
  FileEntry
} from 'computesdk'

const newProvider = createProvider({
  name: 'my-custom-provider',
  methods: {
    sandbox: {
      // Required methods
      async create(options) {
        // Implementation to create a new sandbox
        return {
          sandbox: { id: 'sandbox-123', status: 'running' },
          sandboxId: 'sandbox-123'
        }
      },
      
      async getById(sandboxId) {
        // Implementation to get sandbox by ID
        return {
          sandbox: { id: sandboxId, status: 'running' },
          sandboxId
        }
      },
      
      async list() {
        // Implementation to list all sandboxes
        return []
      },
      
      async destroy(sandboxId) {
        // Implementation to destroy a sandbox
      },
      
      // Core execution methods
      async runCode(code: string, runtime?: Runtime): Promise<ExecutionResult> {
        // Implementation to run code in the sandbox
        return {
          stdout: '',
          stderr: '',
          exitCode: 0,
          executionTime: 0,
          sandboxId: 'sandbox-123',
          provider: 'my-custom-provider'
        }
      },
      
      async runCommand(
        command: string, 
        args?: string[], 
        options?: RunCommandOptions
      ): Promise<ExecutionResult> {
        // Implementation to run a command in the sandbox
        return {
          stdout: '',
          stderr: '',
          exitCode: 0,
          executionTime: 0,
          sandboxId: 'sandbox-123',
          provider: 'my-custom-provider'
        }
      },
      
      // Optional but recommended
      async getInfo(sandboxId: string): Promise<SandboxInfo> {
        return {
          id: sandboxId,
          provider: 'my-custom-provider',
          runtime: 'node',
          status: 'running',
          createdAt: new Date(),
          timeout: 300000,
          metadata: {}
        }
      },
      
      async getUrl(options: { port: number; protocol?: string }): Promise<string> {
        return `https://${options.port}.my-custom-provider.example.com`
      },
      
      // Optional filesystem methods
      filesystem: {
        async readFile(path: string): Promise<string> {
          // Implementation
          return 'file content'
        },
        
        async writeFile(path: string, content: string): Promise<void> {
          // Implementation
        },
        
        async mkdir(path: string): Promise<void> {
          // Implementation
        },
        
        async readdir(path: string): Promise<FileEntry[]> {
          // Implementation
          return []
        },
        
        async exists(path: string): Promise<boolean> {
          // Implementation
          return false
        },
        
        async remove(path: string): Promise<void> {
          // Implementation
        }
      }
    }
  }
})

// Use the provider with createCompute
const compute = createCompute({
  defaultProvider: newProvider
})

Required Methods

Every provider must implement these core methods:

create(options: CreateSandboxOptions)

Creates a new sandbox instance.

getById(sandboxId: string)

Retrieves a sandbox by its ID.

list()

Lists all available sandboxes.

destroy(sandboxId: string)

Destroys a sandbox.

runCode(code: string, runtime?: Runtime)

Executes code in the sandbox.

runCommand(command: string, args?: string[], options?: RunCommandOptions)

Runs a shell command in the sandbox.