SDK runtime management

SDK documentation / Runtime management

Call launch to download the selected Mimic release when needed, start it headless and connect your client. Call connect when a runtime is already running. You do not need to find an executable or install Chromium.

Start with the language and client setup for installation from the SDK's GitHub release.

Choose an exact version

Every SDK package carries a default runtime lock. A no-argument launch uses that pinned release, so a newly published Mimic runtime does not silently change an existing application. SDK package versions and Mimic runtime versions are independent. Updating the SDK may update its default pin; use an explicit runtime version or lock to keep your application on the same one.

Acceptable selectors are exact versions such as 0.2.4,v0.2.4 or an exact beta release. Ranges, latest and wildcard selectors are rejected. An explicit version and lock must agree.

1. An explicit runtime version or runtime lock selects the release.
2. Otherwise, MIMIC_RUNTIME_VERSION selects it.
3. Otherwise, the SDK's packaged default lock selects it.

Selecting another release resolves its manifest from that exact official GitHub release. The SDK verifies the manifest checksum, archive length and checksum, executable checksum and release identity. A saved runtime lock also retains the release's source provenance. Keep it intact instead of assembling one by hand.

One persistent cache across languages

All SDKs reuse this layout. Each release/platform/binary hash has its own installation, so several versions can coexist and concurrent installs do not replace an executable another process is using. Set MIMIC_RUNTIME_DIR or the corresponding language option to choose another root. An explicit option takes precedence over the environment variable.

Cached files are verified before reuse. Installation happens in a temporary staging directory and becomes visible only when complete. The cache must be writable and support atomic filesystem operations; keep it on local storage when sharing it between applications on the same machine. Runtime installation locks do not serialize your browser contexts or pages.

Local auto-install supports Windows amd64 and Linux amd64 with glibc 2.39 or newer. Linux also needs the release's system libraries and fonts; see platform requirements. macOS, ARM64 and musl-based Linux do not have packaged runtime artifacts. Connecting to an already-running runtime does not perform local platform installation checks.

Prepare once, then run without downloads

Installation is explicit when you need it to be: call the runtime manager's install method during setup, then launch with downloads disabled. Importing the SDK, creating a manager and connecting to a running runtime never download or start a browser.

These complete examples use the Playwright client from the setup guide. Run the first preparation step while online; deployment can retain only the offline launch section once the same cache is available.

import { RuntimeManager } from "mimic-browser";
import { launch } from "mimic-browser/playwright";

const options = { runtimeVersion: "0.2.4", timeout: 60_000 };

// Prepare once while downloads are allowed. This does not start a browser.
const executable = await new RuntimeManager(options).install();
console.log(executable);

// Reuse the verified installation without any installer network requests.
const session = await launch({ ...options, allowDownload: false });
try {
  const context = await session.newContext();
  const page = await context.newPage();
  await page.setContent("<title>Offline runtime</title><h1>Ready</h1>");
  console.log(await page.title());
} finally {
  await session.close();
}

from mimic import RuntimeManager
from mimic.playwright.sync_api import launch

options = {"runtime_version": "0.2.4", "timeout": 60}

# Prepare once while downloads are allowed. This does not start a browser.
executable = RuntimeManager(**options).install()
print(executable)

# Reuse the verified installation without any installer network requests.
with launch(**options, allow_download=False) as session:
    context = session.new_context()
    page = context.new_page()
    page.set_content("<title>Offline runtime</title><h1>Ready</h1>")
    print(page.title())

MIMIC_DOWNLOAD=0 disables installer network requests. A missing installation or uncached manifest fails explicitly. It does not disable network access from pages: configure browser networking separately. For a portable environment policy, leave the explicit download option unset; .NET, Java/Kotlin and PHP always honor MIMIC_DOWNLOAD=0, while the other SDKs let an explicitly supplied download option override it.

import { writeFile } from "node:fs/promises";
import { RuntimeManager } from "mimic-browser";

const manager = new RuntimeManager({ runtimeVersion: "0.2.4" });
const lock = await manager.resolveLock();
await writeFile("mimic-runtime.lock.json", JSON.stringify(lock, null, 2) + "\n");
console.log("Saved mimic-runtime.lock.json");

import { readFile } from "node:fs/promises";
import { RuntimeManager } from "mimic-browser";

// Pass the official archive filename as the first command-line argument.
const archivePath = process.argv[2];
if (!archivePath) throw new Error("Supply the downloaded Mimic archive filename");
const lock = JSON.parse(await readFile("mimic-runtime.lock.json", "utf8"));
const executable = await new RuntimeManager({ lock, allowDownload: false })
  .install({ archivePath });
console.log(executable);

Use an executable you provide

Supply an executable option or MIMIC_EXECUTABLE_PATH for a local build or a runtime managed by your deployment. The explicit option wins over the environment variable, then the verified cache is the fallback. A missing or invalid explicit executable is an error; it does not trigger a download of a different binary.

An explicit version still checks the running Mimic version. An explicit lock additionally checks the executable hash before starting it. With an explicit executable and no explicit version, lock or version environment variable, local development builds can run without pretending to be the packaged default release. The SDK still verifies that it connected to Mimic.

Close what your session owns

Launch always starts headless on a dynamically assigned loopback port. Use the session's actual endpoint when passing the runtime to another client; do not assume a fixed port. Connect accepts an HTTP(S) discovery endpoint or browser WS(S) endpoint and checks Mimic identity. It never installs or starts a local process.

Use try/finally, a context manager or your language's disposal construct. Startup failures, attachment failures and supported cancellation paths clean up an owned child. Parent-death behavior depends on the runtime release; explicit session closure is the portable guarantee. The original v0.2.2 Linux runtime does not have the later Unix parent-death watcher.

The SDK retains genuine framework browser, context and page objects. A Playwright driver passed into an integration is borrowed and is not stopped on session close. See contexts and profiles for context ownership and camera and microphone for capture lifetime.

Option names by language

JavaScript/TypeScript and Python accept runtime options directly on launch and on RuntimeManager. Ruby uses keyword arguments. .NET, Java/Kotlin, Go, Rust and PHP use their RuntimeOptions type. Java exposes fields and fluent setters; Kotlin uses the same Java API.

Node's framework option passes connection options to the selected native client. Context emulation belongs in context options, not runtime options. Node and Python expose engine, defaulting to v8; changing it does not imply equal compatibility. .NET, Java/Kotlin and PHP expose Arguments/arguments for extra runtime CLI arguments and reject attempts to override headless mode or the listener.

Downloads, browser proxies and timeouts

Installer traffic fetches official release metadata and archives. A browser context proxy controls page requests and does not proxy these downloads. Configure the native HTTP stack used by your SDK before creating the manager; there is no shared SDK downloadProxy option.

Runtime preparation, process startup and page navigation are separate waits. The values below are runtime-manager defaults, not one end-to-end deadline. Set navigation or selector timeouts through your framework's usual API.

Node connect(endpoint, { timeout, signal, framework }) uses milliseconds for its SDK transport timeout; connection options inside framework retain their native meanings. Python connect(endpoint, timeout=30) uses seconds. Python launch's manager timeout does not change its separate 30-second framework attachment timeout. Cancellation can wait for native cleanup; it is not an instruction to abandon a process still being acquired.

Resolve setup failures

Continue with contexts and profiles,media devices or the launch and connect examples.