Objective

Build on Integrating the mimik Client Library tutorial by learning how to start, stop, reset, configure, and manage the mim OE Runtime from your iOS app using ClientRuntime (the new EdgeEngineClient) and ClientLibrary.

Intended Readers

iOS developers who completed Integrating the mimik Client Library tutorial and are ready to control the runtime.

What You'll Learn

• Starting and stopping the runtime
• Generating an access token for runtime APIs
• Inspecting runtime parameters
• Resetting runtime storage
• Managing automatic runtime lifecycle
• Using an external runtime for Simulator/Mac Catalyst

Prerequisites

• Completed Integrating the mimik Client Library tutorial (“Integrating the mimik Client Library into an iOS project”).
• Xcode with Swift 6.1+ toolchain; iOS 16.0+ deployment target.
• A physical iOS device for embedded/on-device runtime. (For Simulator/Mac Catalyst, use external runtime; see below.)
• A developer mim OE runtime license, available from mimik Developer Console.

The full API reference is available in Xcode’s documentation browser and online.

Imports

Use the same imports as in the Integrating the mimik Client Library tutorial.

1: import EdgeCore
2: import EdgeEngine

Starting the mim OE Runtime

Use ClientRuntime.startRuntime(parameters:) on the main actor. You’ll need your developer license from the mimik Developer Console.

1: @MainActor
2: func startRuntime(license: String) async {
3:     // Optional: check the expected runtime version your app targets
4:     let expectedVersion = ClientLibrary.expectedRuntimeVersion()
5:     print("Expected runtime version:", expectedVersion)
6: 
7:     // Configure startup parameters (adjust as needed)
8:     let params = ClientLibrary.RuntimeParameters(
9:         license: license,
10:         logLevel: .info,
11:         nodeInfoLevel: .on,
12:         localDiscovery: .off,
13:         logFileDir: nil
14:     )
15: 
16:     // Optional: bind runtime port, if your setup requires a specific one
17:     // try? ClientRuntime.configureRuntimePort(to: 8083)
18: 
19:     do {
20:         try await ClientLibrary.startRuntime(parameters: params)
21:         print("✔️ Runtime started")
22:     } catch {
23:         print("❌ Failed to start runtime:", error.localizedDescription)
24:     }
25: }

Common parameters

• license (required)
• logLevel: .trace | .debug | .info | .warn | .error | .critical | .off
• nodeInfoLevel: .on | .off | .name | .hwInfoOnly
• localDiscovery: .on | .off
• nodeName (set on @MainActor)
• logFileDir (optional)

Stopping the mim OE Runtime

Shut down the runtime from the main actor:

1: @MainActor
2: func stopRuntime() {
3:     ClientLibrary.stopRuntime()
4:     print("✔️ Runtime stopped")
5: }

Repeated stops have no effect once the runtime is down.

Generating an Access Token

Authenticate with the DeveloperConsole API and derive an Access Token from your developer console credentials using DeveloperConsole.Auth.authenticate(email:password:).

1: import EdgeCore
2: 
3: struct Tokens {
4:     let accessToken: String
5:     let refreshToken: String?
6: }
7: 
8: /// Authenticates a developer via email/password and returns access/refresh tokens.
9: /// - Important: Store credentials securely (e.g., Keychain). Do not hardcode them.
10: func generateAccessToken(email: String, password: String) async throws -> Tokens {
11: 
12:     // Sign in to the Developer Console
13:     let auth = try await DeveloperConsole.Auth.authenticate(email: email, password: password)
14: 
15:     guard let token = auth.token, let access = token.accessToken else {
16:         throw NSError(domain: "Auth", code: 1, userInfo: [NSLocalizedDescriptionKey: "Missing access token from authentication response"])
17:     }
18: 
19:     return Tokens(accessToken: access, refreshToken: token.refreshToken)
20: }

Inspecting Runtime Parameters

Use ClientRuntime.runtimeParameters() to inspect the current configuration at runtime.

1: func printRuntimeParameters() {
2:     guard let params = ClientLibrary.runtimeParameters() else {
3:         print("ℹ️ Runtime not configured yet.")
4:         return
5:     }
6: 
7:     print("logLevel:", params.logLevel)
8:     print("nodeInfoLevel:", params.nodeInfoLevel)
9:     print("localDiscovery:", params.localDiscovery)
10:     print("logFileDir:", params.logFileDir ?? "<nil>")
11: 
12:     Task { @MainActor in
13:         print("nodeName:", params.nodeName)
14:     }
15: }

Resetting the mim OE Runtime

Reset stops the runtime, removes deployed microservices, and erases runtime storage. This is a main-actor call.

1: @MainActor
2: func resetRuntime() {
3:     do {
4:         try ClientLibrary.resetRuntime()
5:         print("✔️ Runtime storage cleared")
6:     } catch {
7:         print("❌ Reset failed:", error.localizedDescription)
8:     }
9: }

Warning: Reset is destructive—data and deployed microservices are removed.

Lifecycle Management

You can let the Client Library automatically manage the runtime (start/stop on app foreground/background) or control it manually.

1: // Enable/disable automatic lifecycle management
2: func setLifecycleManaged(_ managed: Bool) {
3:     do {
4:         try ClientLibrary.manageRuntimeLifecycle(manage: managed)
5:         print("Lifecycle managed =", managed)
6:     } catch {
7:         print("❌ Failed to set lifecycle management:", error.localizedDescription)
8:     }
9: }
10: 
11: // Query current lifecycle management state
12: func isLifecycleManaged() -> Bool {
13:     ClientLibrary.runtimeLifecycleIsManaged()
14: }

When managed, the Client Library listens for app lifecycle notifications and starts/stops the runtime accordingly.

Using an External Runtime (Simulator & Mac Catalyst)

On Simulator/Mac Catalyst, prefer a hosted external runtime instead of embedding the iOS runtime pod.

Activating external runtime support

Use ClientLibrary.activateExternalRuntime(host:port:) to direct all runtime calls to your hosted instance. You can also query/disable this mode.

1: func activateExternalRuntime(host: String, port: Int) {
2:     do {
3:         let endpoint = try ClientLibrary.activateExternalRuntime(host: host, port: port)
4:         print("✔️ External runtime activated at:", endpoint)
5:     } catch {
6:         print("❌ Activation failed:", error.localizedDescription)
7:     }
8: }
9: 
10: func isExternalRuntimeActive() -> Bool {
11:     ClientLibrary.externalRuntimeIsActivated()
12: }
13: 
14: func deactivateExternalRuntime() {
15:     do {
16:         try ClientLibrary.deactivateExternalRuntime()
17:         print("External runtime deactivated")
18:     } catch {
19:         print("❌ Deactivation failed:", error.localizedDescription)
20:     }
21: }

Example: Run mim OE on 192.168.4.47:8083 and call activateExternalRuntime(host:"192.168.4.47", port:8083) from the Simulator build.

Conditional imports (optional)

1: import EdgeCore
2: #if !DEVICE   // set via "Active Compilation Conditions"
3: import EdgeEngine
4: #endif

Podfile targets (optional)

1: target 'device-runtime-target' do
2:   pod 'EdgeCore'
3:   pod 'mim-OE-ai-SE-iOS-developer'
4: end
5: 
6: target 'simulator-runtime-target' do
7:   pod 'EdgeCore'
8: end

Mac computers with Apple silicon

Most iPhone/iPad apps run natively on Apple silicon Macs. Xcode supports debugging, testing, and profiling these builds much like Simulator/device workflows. If you run with an external runtime, configure its host/port and activate it as shown above.

Troubleshooting

• Build issues / toolchain — Ensure Swift 6.1+ and iOS 16.0+ targets.
• Start is a no-op — if the runtime is already running, calling startRuntime again does nothing. Make sure you pass a valid developer runtime license and call it on @MainActor.
• Stop/reset feels blocking — They execute on the main actor; avoid additional long tasks on the main thread at the same time.
• Simulator requests fail — Confirm external runtime is activated and reachable from the Simulator (host network and port open).

Next

Proceed to “Working with edge microservices in an iOS project” to discover/deploy a microservice and call it from your app using request helpers.