Configuration

Initialization

One call sets everything up. Platform adapters, native load, authentication, device registration, and catalog sync all happen inside it. The network parts run in the background and retry, so the call returns as soon as local inference is usable.

try RunAnywhere.initialize(environment: .development)

try RunAnywhere.initialize(
    apiKey: "<YOUR_API_KEY>",
    baseUrl: "https://api.runanywhere.ai",
    environment: .production
)

Parameter	Type	Default	Description
`apiKey`	`String?`	`nil`	`nil` runs in keyless local mode
`baseUrl`	`String?`	`nil`	`nil` uses the environment’s default
`environment`	`SDKEnvironment`	`.production`	Log level and auth behavior

initialize is synchronous and throws. There is no second phase to await.

SDKEnvironment

public typealias SDKEnvironment = RASDKEnvironment
// cases: .unspecified, .development, .production

Environment	Log level	Authentication	Telemetry
`.development`	Debug	Optional	Local
`.production`	Warning	Required	Yes

There is no staging case. Point baseUrl at a staging deployment and keep environment: .production.

Module registration

Register backends before initialize(). The C++ plugin registry resolves an engine on the first model load, and with nothing registered that load fails.

import RunAnywhere
import LlamaCPPRuntime
import ONNXRuntime
import MLXRuntime

@MainActor
func configureSDK() {
    LlamaCPP.register()              // LLM and VLM via llama.cpp
    ONNX.register()                  // registers Sherpa-ONNX for STT, TTS, VAD
    let mlxReady = MLX.register()    // false when MLX is unavailable
}

All three are @MainActor and idempotent. MLX.register() returns Bool and reports false in the Simulator, where the MLX runtime is unavailable. The other two return Void and log rather than throw.

Engine priority

register(priority:) accepts a priority argument for source compatibility but ignores it. Selection happens in the C++ registry using each plugin’s base priority, per primitive:

Engine	Base priority
qhexrt	150
mlx	110
llamacpp	100
sherpa	90
onnx	50
cloud	50

To pin an engine for one model, pass LoadOptions(framework:) to models.load.

The models namespace

func list(filter: ModelFilter? = nil) async throws -> [ModelInfo]
func get(id: String) async -> ModelInfo?
func register(_ registration: ModelRegistration) async throws -> ModelInfo
func download(id: String) async throws -> AsyncThrowingStream<DownloadEvent, Error>
func delete(id: String) async throws
func load(id: String, options: LoadOptions? = nil) async throws
func unload(category: ModelCategory? = nil) async throws
func state() async -> ModelsState
func refresh(rescanLocal:includeRemoteCatalog:pruneOrphans:) async

Generation verbs auto-load, so load is for callers who want to choose when the cost is paid.

Registering models

ModelRegistration is one builder with three factories.

let model = try await RunAnywhere.models.register(
    .url(
        "https://huggingface.co/LiquidAI/LFM2-350M-GGUF/resolve/main/LFM2-350M-Q4_K_M.gguf",
        name: "LFM2 350M Q4_K_M",
        framework: .llamaCpp,
        category: .language,
        id: "lfm2-350m-q4_k_m",
        memoryRequirementBytes: 300_000_000
    )
)

let stt = try await RunAnywhere.models.register(
    .archive(
        "https://.../sherpa-onnx-whisper-tiny.en.tar.gz",
        structure: .nestedDirectory,
        name: "Sherpa Whisper Tiny",
        framework: .onnx,
        category: .speechRecognition,
        archiveType: .tarGz,
        id: "sherpa-onnx-whisper-tiny.en",
        memoryRequirementBytes: 75_000_000
    )
)

let vlm = try await RunAnywhere.models.register(
    .multiFile(
        [descriptor(modelURL, "model.gguf"), descriptor(projectorURL, "mmproj.gguf")],
        id: "smolvlm-256m-instruct",
        name: "SmolVLM 256M Instruct",
        framework: .llamaCpp,
        category: .multimodal,
        memoryRequirementBytes: 365_000_000
    )
)

id is optional on .url and .archive, where commons derives one from the URL. .multiFile requires it. ArchiveType: .zip, .tarGz, .tarBz2, .tarXz. ArchiveStructure: .singleFileNested, .directoryBased, .nestedDirectory, .unknown.

InferenceFramework

Value	Description
`.llamaCpp`	LLM and VLM via llama.cpp (GGUF)
`.onnx`	ONNX Runtime
`.sherpa`	Sherpa-ONNX for STT, TTS, and VAD
`.mlx`	MLX on Apple Silicon
`.coreml`	Apple CoreML, including diffusion
`.foundationModels`	Apple Foundation Models
`.systemTts`	AVSpeechSynthesizer voices

InferenceFramework is a typealias for RAInferenceFramework, and ModelCategory for RAModelCategory.

Downloading

One verb reports progress and completion on the same stream. percent runs 0 to 100.

for try await event in try await RunAnywhere.models.download(id: model.id) {
    switch event {
    case .progress(let done, let total, let percent):
        print("\(Int(percent))% (\(done)/\(total))")
    case .extracting:
        print("Extracting")
    case .completed(let refreshed):
        print("Ready at \(refreshed.localPath)")
    }
}

The factory throws when the id is unknown. Transfer failures throw into the loop.

Loading and unloading

Both throw on failure. Neither returns a result to inspect.

try await RunAnywhere.models.load(id: model.id)

try await RunAnywhere.models.unload(category: .language)
try await RunAnywhere.models.unload()   // everything

LoadOptions carries placement knobs:

try await RunAnywhere.models.load(
    id: model.id,
    options: LoadOptions(framework: .llamaCpp)
)

Field	Type	Notes
`framework`	`InferenceFramework?`	Engine pin, honored at load time
`contextLength`	`Int?`	Accepted, not yet carried by the ABI
`threads`	`Int?`	Accepted, not yet carried by the ABI
`useGpu`	`Bool?`	Accepted, not yet carried by the ABI

Only framework reaches commons today. The other three are logged and dropped because the native load ABI does not carry them.

Querying the registry

let all = try await RunAnywhere.models.list()

let voices = try await RunAnywhere.models.list(
    filter: ModelFilter(category: .speechSynthesis, downloadedOnly: true)
)

let model = await RunAnywhere.models.get(id: "lfm2-350m-q4_k_m")   // ModelInfo?

ModelFilter takes category, framework, downloadedOnly, and search. get returns nil for an unknown id rather than throwing.

What is loaded

let state = await RunAnywhere.models.state()

print(state.loaded[.language]?.id ?? "no LLM")
print("Models on disk: \(state.storageUsedBytes) bytes")
print("Free: \(state.storageFreeBytes) bytes")

ModelsState.loaded is keyed by ModelCategory, so one read tells you the whole picture. models.refresh() rescans the managed model directories and reconciles downloaded state, which is worth calling once at launch.

Options types

Every options struct has a memberwise initializer and per-field defaults read from the IDL, so the values match every other SDK.

LlmOptions

var options = LlmOptions()
options.maxOutputTokens = 200
options.temperature = 0.3
options.topP = 0.9

Option	Default
`maxOutputTokens`	512
`temperature`	0.7
`topP`	1.0
`maxToolCalls`	5
`toolChoice`	`.auto`

See generate() for the full list, including reasoning and structuredOutput.

SttOptions

var options = SttOptions()
options.language = "es"
options.wordTimestamps = true

Option	Default
`language`	`nil`, auto-detect
`punctuation`	`true`
`wordTimestamps`	`true`
`diarization`	`false`

The language is a BCP-47 string, not an enum. See STT Options.

TtsOptions

var options = TtsOptions()
options.speed = 0.9

Option	Default
`voice`	`nil`
`language`	`"en-US"`
`speed`	`1.0`
`pitch`	`1.0`
`format`	`.pcm`
`sampleRate`	`22050`

VadOptions

var options = VadOptions()
options.minSilenceMs = 400

Option	Default
`activationThreshold`	`nil`, model’s calibration
`minSpeechMs`	100
`minSilenceMs`	300
`prefixPaddingMs`	0

Others

ImageOptions, EmbedOptions, DiarizationOptions, SegmentationOptions, RagConfig, TurnHandlingOptions, and LoadOptions follow the same pattern. Each is documented on the page for its namespace.

LoRA adapters

Adapters register through the model registry, then apply to whatever base model is loaded.

try await RunAnywhere.lora.apply(adapterId: "chat-tuned", scale: 0.8)

let state = try await RunAnywhere.lora.list()
for adapter in state.applied {
    print("\(adapter.id) at scale \(adapter.scale)")
}

try await RunAnywhere.lora.remove(adapterId: "chat-tuned")
try await RunAnywhere.lora.remove()   // remove all

apply throws when the adapter is unknown, has no local file, or is incompatible with the loaded base model. scale of nil uses the catalog default.

Storage

var request = RAStorageInfoRequest()
request.includeDevice = true
request.includeApp = true
request.includeModels = true

let result = await RunAnywhere.getStorageInfo(request)
guard result.success else { return }

print("Device free: \(result.info.device.freeBytes)")
print("App documents: \(result.info.app.documentsBytes)")

try await RunAnywhere.models.delete(id: "lfm2-350m-q4_k_m")
try await RunAnywhere.clearCache()
try await RunAnywhere.cleanTempFiles()

For a quick read on space without the request struct, models.state() reports storageUsedBytes and storageFreeBytes.

Logging

RunAnywhere.setLogLevel(.debug)
RunAnywhere.setLocalLoggingEnabled(true)
RunAnywhere.setDebugMode(true)
RunAnywhere.flushLogs()

var config = RALoggingConfiguration.defaults()
config.minLogLevel = .info
config.includeSourceLocation = true
RunAnywhere.configureLogging(config)

RALoggingConfiguration.defaults() sets enableLocalLogging = true and leaves the rest at their zero values, which makes minLogLevel default to .trace. RALogLevel, lowest to highest: .trace, .debug, .info, .warning, .error, .fatal. There is no .fault case.

SDK state

let ready = RunAnywhere.isReady
let version = RunAnywhere.version
let deviceId = RunAnywhere.deviceId
let environment = RunAnywhere.environment   // SDKEnvironment?

let isAuthenticated = RunAnywhere.isAuthenticated
let userId = RunAnywhere.getUserId()
let orgId = RunAnywhere.getOrganizationId()
let isRegistered = RunAnywhere.isDeviceRegistered()

isReady means local inference is usable. The older isInitialized, isActive, and areServicesReady are deprecated: network readiness is an SDK-internal concern now, and calls wait for it themselves.

Events

RunAnywhere.events is an AsyncStream<SdkEvent> of lifecycle breadcrumbs.

for await event in RunAnywhere.events {
    switch event {
    case .ready:
        print("SDK ready")
    case .modelLoaded(let id, let category):
        print("Loaded \(id) as \(category)")
    case .modelUnloaded(let id):
        print("Unloaded \(id)")
    case .error(let message, let recoverable):
        print("\(recoverable ? "warning" : "error"): \(message)")
    }
}

When you need a field SdkEvent folds away, such as download byte counts or per-component progress, RunAnywhere.eventBus exposes the raw proto envelopes through Combine.

import Combine

var cancellables = Set<AnyCancellable>()

RunAnywhere.eventBus.errorEvents
    .receive(on: DispatchQueue.main)
    .sink { event in logger.error("SDK event: \(event.category)") }
    .store(in: &cancellables)

EventBus also exposes llmEvents, sttEvents, ttsEvents, modelEvents, ragEvents, sdkEvents, and events(for:).

Environment-specific setup

func configureForEnvironment() {
    #if DEBUG
    try? RunAnywhere.initialize(environment: .development)
    RunAnywhere.setLogLevel(.debug)
    RunAnywhere.setDebugMode(true)
    #else
    try? RunAnywhere.initialize(
        apiKey: ProcessInfo.processInfo.environment["RUNANYWHERE_API_KEY"],
        baseUrl: "https://api.runanywhere.ai",
        environment: .production
    )
    RunAnywhere.setLogLevel(.warning)
    #endif
}

Reset

await RunAnywhere.reset()

reset() unloads models, closes sessions, and clears state including authentication. It is async and does not throw.

Use reset() in development and tests only.

Error Handling

Handle SDK errors

Best Practices

Performance patterns

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

Initialization

SDKEnvironment

Module registration

Engine priority

The models namespace

Registering models

InferenceFramework

Downloading

Loading and unloading

Querying the registry

What is loaded

Options types

LlmOptions

SttOptions

TtsOptions

VadOptions

Others

LoRA adapters

Storage

Logging

SDK state

Events

Environment-specific setup

Reset

Error Handling

Best Practices

​Initialization

​SDKEnvironment

​Module registration

​Engine priority

​The models namespace

​Registering models

​InferenceFramework

​Downloading

​Loading and unloading

​Querying the registry

​What is loaded

​Options types

​LlmOptions

​SttOptions

​TtsOptions

​VadOptions

​Others

​LoRA adapters

​Storage

​Logging

​SDK state

​Events

​Environment-specific setup

​Reset

Error Handling

Best Practices

Initialization

SDKEnvironment

Module registration

Engine priority

The models namespace

Registering models

InferenceFramework

Downloading

Loading and unloading

Querying the registry

What is loaded

Options types

LlmOptions

SttOptions

TtsOptions

VadOptions

Others

LoRA adapters

Storage

Logging

SDK state

Events

Environment-specific setup

Reset