Skip to main content

​
Package Installation

Install the @limrun/api package using your preferred package manager: 
npm install @limrun/api

​
Requirements

​
TypeScript Version

The SDK requires TypeScript 4.9 or later for full type support and IntelliSense features.
package.json
{
  "devDependencies": {
    "typescript": "^4.9.0"
  }
}
While TypeScript is recommended, the SDK works perfectly fine with plain JavaScript. Type definitions are included for editor autocomplete.

​
Supported Runtimes

The Limrun SDK works across multiple JavaScript runtimes:
RuntimeMinimum VersionNotes
Node.js20 LTS or laterRecommended for server-side usage
Denov1.28.0+Native ESM support
Bun1.0+Fast native performance
Cloudflare WorkersLatestEdge runtime support
Vercel Edge RuntimeLatestServerless edge functions
Web BrowsersModern browsersChrome, Firefox, Safari, Edge
Jest28+Use node environment (not jsdom)
Nitrov2.6+Nuxt and Nitro server support
React Native is not supported at this time. If you need React Native support, please open an issue on GitHub.

​
Environment Setup

​
API Key Configuration

The SDK requires a Limrun API key for authentication. You can obtain one by signing up at lim.run. Set the LIM_API_KEY environment variable: 
export LIM_API_KEY="your-api-key-here"

​
Passing the API Key Directly

Alternatively, pass the API key when creating the client: 
import Limrun from '@limrun/api';

const limrun = new Limrun({
  apiKey: 'your-api-key-here',
});
Never commit API keys to version control. Use environment variables or a secure secret management system.

​
Runtime-Specific Setup

​
Node.js

Node.js 20+ has built-in fetch support. No additional configuration needed: 
import Limrun from '@limrun/api';

const limrun = new Limrun({
  apiKey: process.env.LIM_API_KEY,
});

​
Deno

Import from npm using the npm: specifier: 
import Limrun from 'npm:@limrun/api';

const limrun = new Limrun({
  apiKey: Deno.env.get('LIM_API_KEY'),
});

​
Bun

Bun works out of the box with native performance: 
import Limrun from '@limrun/api';

const limrun = new Limrun({
  apiKey: process.env.LIM_API_KEY,
});

​
Cloudflare Workers

Use the SDK in Cloudflare Workers for edge-based mobile automation: 
import Limrun from '@limrun/api';

export default {
  async fetch(request: Request, env: Env) {
    const limrun = new Limrun({
      apiKey: env.LIM_API_KEY,
    });

    const instance = await limrun.iosInstances.create({ wait: true });
    return new Response(JSON.stringify(instance));
  },
};

​
Vercel Edge Runtime

Deploy mobile automation to Vercel Edge Functions: 
import Limrun from '@limrun/api';
import type { NextRequest } from 'next/server';

export const runtime = 'edge';

export async function GET(request: NextRequest) {
  const limrun = new Limrun({
    apiKey: process.env.LIM_API_KEY,
  });

  const instance = await limrun.androidInstances.create({ wait: true });
  return Response.json(instance);
}

​
Web Browsers

The SDK works in modern browsers (avoid exposing API keys in client-side code): 
<script type="module">
  import Limrun from 'https://esm.sh/@limrun/api';

  const limrun = new Limrun({
    apiKey: 'your-api-key', // Use a proxy server in production!
  });

  const instance = await limrun.iosInstances.create({ wait: true });
  console.log(instance);
</script>
Never expose your API key in client-side browser code. Use a backend proxy or serverless function to make authenticated requests.

​
Module Systems

The SDK supports both CommonJS and ES Modules: 
import Limrun from '@limrun/api';
import { Ios, createInstanceClient } from '@limrun/api';

​
CommonJS

const Limrun = require('@limrun/api').default;
const { Ios, createInstanceClient } = require('@limrun/api');

​
Type Imports

Import TypeScript types for better IDE support: 
import Limrun, {
  type AndroidInstance,
  type IosInstance,
  type ScreenshotData,
  type AccessibilitySelector,
} from '@limrun/api';

const instance: Limrun.IosInstance = await client.iosInstances.create();
All request parameters and response types are fully typed with documentation in docstrings: 
// Hover over methods in your editor to see type hints
const screenshot: ScreenshotData = await client.screenshot();
//    ^? { base64: string; width: number; height: number }

​
Verification

Verify your installation by creating a simple test:
test.ts
import Limrun from '@limrun/api';

const limrun = new Limrun({
  apiKey: process.env.LIM_API_KEY,
});

// List existing iOS instances
const instances = await limrun.iosInstances.list();
console.log(`Found ${instances.items.length} iOS instances`);

for await (const instance of limrun.iosInstances.list()) {
  console.log(`- ${instance.metadata.id} (${instance.status.state})`);
}
Run it: 
node test.ts

​
Optional Dependencies

The SDK has minimal required dependencies but integrates with popular tools:

​
WebSocket Support

WebSocket functionality uses the ws package (included as a dependency): 
{
  "dependencies": {
    "ws": "^8.18.3"
  }
}

​
File Synchronization

The iOS client includes folder sync capabilities using the ignore package: 
{
  "dependencies": {
    "ignore": "^7.0.5"
  }
}

​
Server-Sent Events

For streaming responses (used in log streaming): 
{
  "dependencies": {
    "eventsource-client": "^1.2.0"
  }
}

​
Troubleshooting

​
Fetch Not Defined

If you’re using Node.js 18 or earlier: 
npm install node-fetch

import fetch from 'node-fetch';
globalThis.fetch = fetch as any;

​
TypeScript Errors

Ensure you’re using TypeScript 4.9+: 
npm install -D typescript@latest

​
Module Resolution

If you encounter module resolution issues, configure your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022",
    "lib": ["ES2022"]
  }
}

​
Jest Configuration

When using Jest, ensure you’re using the node environment:
jest.config.js
module.exports = {
  testEnvironment: 'node', // Not 'jsdom'
};

​
Next Steps

Quickstart

Create your first iOS or Android instance

API Reference

Explore the complete API documentation

Authentication

Learn about API keys and security best practices

Error Handling

Handle errors and retries effectively
The SDK is generated using Stainless and follows semantic versioning. Check the changelog for updates.

Build docs developers (and LLMs) love

Get started for freeTalk to us