Migrate from Runloop

@solarisdk/runloop-compat (TypeScript) and solari-runloop-compat (Python) expose the Runloop devbox API on top of Solari sandboxes. Change the import, set a Solari API key, and keep your devbox code. Anything Solari cannot do throws a clear SolariCompatUnsupported error naming the feature; nothing is silently ignored.

Install

npm install @solarisdk/runloop-compat     # TypeScript
pip install solari-runloop-compat          # Python (import solari_runloop)

Change the import

// before: import { RunloopSDK } from "@runloop/api-client"
import { RunloopSDK } from "@solarisdk/runloop-compat"

const sdk = new RunloopSDK({ bearerToken: process.env.SOLARI_API_KEY })
const devbox = await sdk.devbox.create({ name: "demo" })

await devbox.file.write({ file_path: "main.py", contents: "print('hello from a sandbox')" })
const result = await devbox.cmd.exec("python3 main.py")
console.log(await result.stdout(), result.exitCode)

await devbox.shutdown()

# before: from runloop_api_client import RunloopSDK
from solari_runloop import RunloopSDK

runloop = RunloopSDK()  # reads SOLARI_API_KEY

with runloop.devbox.create(name="demo") as devbox:
    devbox.file.write(file_path="main.py", contents="print('hello from a sandbox')")
    result = devbox.cmd.exec("python3 main.py")
    print(result.stdout(), result.exit_code)

Runloop (the REST layer, client.devboxes.*), RunloopSDK (the object layer) and, in Python, AsyncRunloop and AsyncRunloopSDK are exported under Runloop’s names, together with Runloop’s error classes.

Suspend, resume and snapshot

await devbox.suspend()   // Solari pause: keeps memory and disk
await devbox.resume()

const snapshot = await devbox.snapshotDisk({ name: "after-setup" })
const clone = await snapshot.createDevbox({ name: "clone" })
await clone.shutdown()
await snapshot.delete()

Configuration

• API key. The bearerToken / apiKey option (Python: bearer_token), then SOLARI_API_KEY, then RUNLOOP_API_KEY. Only a Solari key (slr_…) is ever used. A Runloop key left in the environment is skipped with a warning and is never sent anywhere; with no Solari key the constructor throws.
• Base URL. The baseURL option, then SOLARI_BASE_URL, then RUNLOOP_BASE_URL, default https://api.getsolari.com. RUNLOOP_BASE_URL is honoured only when it points at Solari or loopback. Passing any other host explicitly throws, so your Solari key can never reach Runloop’s servers.

What works

Devboxes

Commands, files and snapshots

Tunnels, blueprints and secrets

Not supported

These throw SolariCompatUnsupported, which is an APIError:

• onEvict and cancelOnEvict, SSH keys, and closeStdIn.
• Object mounts, code_mounts, gateways, mcp, network_policy_id, required_services and any create parameter the package does not know.
• agent, axon, networkPolicy, gatewayConfig, mcpConfig and the matching client.agents, client.axons, client.networkPolicies, client.gatewayConfigs and client.mcpConfigs calls.
• Non-empty defaultHeaders, defaultQuery and httpAgent.

The full matrix, with every call, is in the COMPAT.md that ships with each package.

Errors

Errors keep Runloop’s classes, so existing catch blocks keep working:

import { NotFoundError, SolariCompatUnsupported } from "@solarisdk/runloop-compat"

try {
  await sdk.devbox.fromId("does-not-exist").getInfo()
} catch (e) {
  if (e instanceof NotFoundError) console.log(e.status) // 404
}

try {
  await devbox.shell("build") // TypeScript: not supported
} catch (e) {
  console.log(e instanceof SolariCompatUnsupported) // true
}

.error carries Solari’s error body (code, message, retryable).