Skip to main content

​
Overview

This guide covers SDK initialization options, environment configuration, logging, and event subscriptions.

​
SDK Initialization

​
Basic Initialization

import { RunAnywhere, SDKEnvironment } from '@runanywhere/core'

// Development mode (no API key required)
await RunAnywhere.initialize({
  environment: SDKEnvironment.Development,
})

​
Production Initialization

await RunAnywhere.initialize({
  apiKey: 'your-api-key',
  baseURL: 'https://api.runanywhere.ai',
  environment: SDKEnvironment.Production,
})

​
Full Configuration

interface SDKInitOptions {
  /** API key for authentication (production/staging) */
  apiKey?: string

  /** Base URL for API requests */
  baseURL?: string

  /** SDK environment */
  environment?: SDKEnvironment

  /** Supabase project URL (development mode only) */
  supabaseURL?: string

  /** Supabase anon key (development mode only) */
  supabaseKey?: string

  /** Enable debug logging */
  debug?: boolean
}

​
Environment Modes

EnvironmentDescriptionAPI KeyLogging
DevelopmentLocal development, full debuggingOptionalDebug
StagingTesting with real servicesRequiredInfo
ProductionProduction deploymentRequiredWarning
enum SDKEnvironment {
  Development = 'development',
  Staging = 'staging',
  Production = 'production',
}

​
Logging

​
Set Log Level

import { RunAnywhere, LogLevel } from '@runanywhere/core'

// Set minimum log level
RunAnywhere.setLogLevel(LogLevel.Debug)

​
Log Levels

LevelDescriptionUse Case
DebugDetailed debugging infoDevelopment
InfoGeneral informationStaging
WarningPotential issuesProduction
ErrorErrors and failuresProduction
FaultCritical failuresAlways

​
Custom Logger (Advanced)

SDKLogger is used internally by the SDK. For most apps, the built-in logging controlled by setLogLevel() is sufficient.
import { SDKLogger } from '@runanywhere/core'

// Create a custom logger
const logger = new SDKLogger('MyApp')

logger.debug('Debug message', { modelId: 'llama-2' })
logger.info('Info message')
logger.warning('Warning message')
logger.error('Error message', new Error('Something went wrong'))

​
Events

​
EventBus

The SDK provides a comprehensive event system for monitoring SDK activities. 
import { RunAnywhere, EventBus, EventCategory } from '@runanywhere/core'

// Access EventBus via RunAnywhere
RunAnywhere.events.onGeneration((event) => {
  console.log('Generation event:', event.type)
})

// Or use EventBus directly
EventBus.on('Generation', (event) => {
  console.log('Event:', event)
})

​
Event Categories

CategoryEvents
Initializationstarted, completed, failed
Generationstarted, tokenGenerated, completed, failed, cancelled
ModeldownloadStarted, downloadProgress, downloadCompleted, loadStarted, loadCompleted, unloaded
VoicesttStarted, sttCompleted, ttsStarted, ttsCompleted, vadSpeechStarted, vadSpeechEnded
Storagecleared, modelDeleted
ErrorVarious error events

​
Event Subscription Examples

// Initialization events
const unsubInit = RunAnywhere.events.onInitialization((event) => {
  switch (event.type) {
    case 'started':
      console.log('SDK initializing...')
      break
    case 'completed':
      console.log('SDK ready!')
      break
    case 'failed':
      console.error('Init failed:', event.error)
      break
  }
})

// Generation events
const unsubGen = RunAnywhere.events.onGeneration((event) => {
  switch (event.type) {
    case 'started':
      console.log('Generation started')
      break
    case 'tokenGenerated':
      // Append token to your UI state
      setResponse((prev) => prev + event.token)
      break
    case 'completed':
      console.log('Done:', event.response.text)
      break
    case 'failed':
      console.error('Failed:', event.error)
      break
  }
})

// Model events
const unsubModel = RunAnywhere.events.onModel((event) => {
  switch (event.type) {
    case 'downloadProgress':
      console.log(`${event.modelId}: ${(event.progress * 100).toFixed(1)}%`)
      break
    case 'downloadCompleted':
      console.log(`${event.modelId} downloaded`)
      break
    case 'loadCompleted':
      console.log(`${event.modelId} loaded`)
      break
  }
})

// Voice events
const unsubVoice = RunAnywhere.events.onVoice((event) => {
  switch (event.type) {
    case 'sttStarted':
      console.log('Transcription started')
      break
    case 'sttCompleted':
      console.log('Transcript:', event.result.text)
      break
    case 'vadSpeechStarted':
      console.log('Speech detected')
      break
    case 'vadSpeechEnded':
      console.log('Speech ended')
      break
  }
})

// Clean up subscriptions
unsubInit()
unsubGen()
unsubModel()
unsubVoice()

​
SDK State

​
Check Initialization

// Check if SDK is initialized
const isInit = await RunAnywhere.isInitialized()

// Check properties
console.log('Initialized:', RunAnywhere.isSDKInitialized)
console.log('Services ready:', RunAnywhere.areServicesReady)
console.log('Environment:', RunAnywhere.currentEnvironment)
console.log('Version:', RunAnywhere.version)
console.log('Device ID:', RunAnywhere.deviceId)

​
Reset SDK

// Reset to uninitialized state
await RunAnywhere.reset()

// Or use destroy (alias)
await RunAnywhere.destroy()

// Can now reinitialize with different options
await RunAnywhere.initialize({
  environment: SDKEnvironment.Production,
  apiKey: 'new-api-key',
})

​
Model Configuration

​
Generation Options

const options: GenerationOptions = {
  maxTokens: 256, // Max tokens to generate
  temperature: 0.7, // Sampling temperature (0.0-2.0)
  topP: 0.95, // Nucleus sampling
  stopSequences: ['END'], // Stop sequences
  systemPrompt: 'You are helpful.', // System prompt
  preferredExecutionTarget: ExecutionTarget.OnDevice,
  preferredFramework: LLMFramework.LlamaCpp,
}

​
STT Options

const sttOptions: STTOptions = {
  language: 'en', // Language code
  punctuation: true, // Add punctuation
  wordTimestamps: true, // Include word timing
  sampleRate: 16000, // Audio sample rate
}

​
TTS Options

const ttsOptions: TTSConfiguration = {
  voice: 'en-US-female-1', // Voice ID
  rate: 1.0, // Speech rate (0.5-2.0)
  pitch: 1.0, // Pitch (0.5-2.0)
  volume: 1.0, // Volume (0.0-1.0)
}

​
Storage Configuration

​
Get Storage Info

const storage = await RunAnywhere.getStorageInfo()

console.log('Total space:', storage.totalSpace)
console.log('Used by SDK:', storage.usedSpace)
console.log('Free space:', storage.freeSpace)
console.log('Models path:', storage.modelsPath)

​
Clean Up Storage

// Clear SDK cache
await RunAnywhere.clearCache()

// Clean temp files
await RunAnywhere.cleanTempFiles()

// Delete a specific model
await RunAnywhere.deleteModel('model-id')

​
React Native Specific

​
App Lifecycle

import { AppState, AppStateStatus } from 'react-native'

// Handle app state changes
useEffect(() => {
  const subscription = AppState.addEventListener('change', (state: AppStateStatus) => {
    if (state === 'background') {
      // Optionally unload models to free memory
      RunAnywhere.unloadModel()
    } else if (state === 'active') {
      // Reload model if needed
    }
  })

  return () => subscription.remove()
}, [])

​
Memory Warnings

Use the SDK’s event system to handle low-memory situations: 
import { AppState } from 'react-native'
import { RunAnywhere } from '@runanywhere/core'

// Listen for OS memory warnings via the performance event bus
RunAnywhere.events.onPerformance((event) => {
  if (event.type === 'memoryWarning') {
    console.log('Memory warning — usage:', event.usage)
    // Free memory by unloading unused models
    RunAnywhere.unloadModel()
  }
})

// Also listen for unexpected model unloads
RunAnywhere.events.onModel((event) => {
  if (event.type === 'unloadCompleted') {
    console.log('Model was unloaded')
  }
})

// Proactively unload models when the app backgrounds
useEffect(() => {
  const subscription = AppState.addEventListener('change', (state) => {
    if (state === 'background') {
      RunAnywhere.unloadModel()
    }
  })
  return () => subscription.remove()
}, [])

​
Model Management

​
Check Model Status

// Check if a specific model is loaded in memory
const loaded = await RunAnywhere.isModelLoaded()

// Check if a model has been downloaded
const downloaded = await RunAnywhere.isModelDownloaded('smollm2-360m')

// Get all registered models
const models = await RunAnywhere.getAvailableModels()
for (const model of models) {
  console.log(
    `${model.id}: ${model.name} (${model.isDownloaded ? 'downloaded' : 'not downloaded'})`
  )
}

// Get detailed info for a model
const info = await RunAnywhere.getModelInfo('smollm2-360m')
console.log('Local path:', info.localPath)

​
Audio Utilities

The SDK provides a built-in RunAnywhere.Audio utility for recording, playback, and audio conversion in React Native.

​
Constants

RunAnywhere.Audio.SAMPLE_RATE // 16000 (STT default)
RunAnywhere.Audio.TTS_SAMPLE_RATE // 22050 (TTS default)

​
Recording

// Request microphone permission
await RunAnywhere.Audio.requestPermission()

// Start recording audio
await RunAnywhere.Audio.startRecording()

// Stop recording and get the recorded file
const recording = await RunAnywhere.Audio.stopRecording()
// recording.uri       - path to the recorded WAV file
// recording.durationMs - recording duration in milliseconds

// Cancel recording without saving
await RunAnywhere.Audio.cancelRecording()

​
Playback

// Play base64-encoded audio
await RunAnywhere.Audio.playAudio(wavBase64)

// Playback controls
await RunAnywhere.Audio.stopPlayback()
await RunAnywhere.Audio.pausePlayback()
await RunAnywhere.Audio.resumePlayback()

​
Audio Conversion

// Convert TTS output (float32 PCM) to playable WAV format
const wavBase64 = RunAnywhere.Audio.createWavFromPCMFloat32(ttsResult.audio, ttsResult.sampleRate)

// Then play it
await RunAnywhere.Audio.playAudio(wavBase64)

​
Cleanup

// Release audio resources
await RunAnywhere.Audio.cleanup()

​
Helper

// Format seconds to "mm:ss" string
const formatted = RunAnywhere.Audio.formatDuration(125) // "2:05"

Error Handling

Handle errors gracefully

Best Practices

Optimization tips