Asset Storage

Asset Storage is Limrun's managed store for app binaries. A boot install means the device starts with the app ready, and a live install swaps in a new build without restarting the session. Build commands upload to it, preview links read from it, and platforms use it to hold their users' apps.

What an asset is

An asset is one stored file. Installable files are iOS simulator builds (.app, .app.zip, or .app.tar.gz) and Android APKs (.apk). Build uploads can also store signed device artifacts, such as an IPA from Sign and distribute or an AAB from Sign and publish, and lim ios keychain save stores encrypted keychain archives. Its record has this shape:

interface Asset {
  id:                string;
  name:              string;
  kind:              'App' | 'Keychain';               // defaults to App
  displayName?:      string;
  md5?:              string;                           // present only once bytes are uploaded
  platform?:         'ios' | 'android' | 'xcode';      // unset = usable on any platform
  expiresAt?:        string;                           // when set, the time the asset is deleted automatically
  signedDownloadUrl?: string;                          // returned when includeDownloadUrl=true
  signedUploadUrl?:   string;                          // returned when includeUploadUrl=true
}

Upload an asset

Pick the upload path by who holds the file:

• getOrUpload (CLI lim asset push) when your code or CI has the file locally. It skips the upload when the bytes are already stored.
• getOrCreate when something else does the upload, such as a worker on another host, a streaming source, or an end user's browser.

Upload a local file

getOrUpload computes the local file's MD5, checks Asset Storage for an entry with the same name and MD5, and skips the transfer when they match. It ships in the TypeScript and Go SDKs; from Python, use the two-step upload.

Upload a local build under a name of your choice:

lim asset push ./build/MyApp.app.tar.gz -n my-app-v1.2.3.tar.gz

import Limrun from '@limrun/api';

const lim = new Limrun({ apiKey: process.env['LIM_API_KEY'] });

const asset = await lim.assets.getOrUpload({
  path: './build/MyApp.app.tar.gz',
  name: 'my-app-v1.2.3.tar.gz',     // optional, defaults to the file's basename
});

// asset.id, asset.name, asset.signedDownloadUrl, asset.md5

asset, err := lim.Assets.GetOrUpload(ctx, limrun.AssetGetOrUploadParams{
    Path: "./build/MyApp.app.tar.gz",
    Name: param.NewOpt("my-app-v1.2.3.tar.gz"), // optional
})
// asset.ID, asset.Name, asset.SignedDownloadURL, asset.Md5

When the MD5 matches an existing upload, the call returns the existing asset's URLs and transfers no bytes.

Limrun's iOS preview GitHub Action gives each pull request its own asset slot with a naming convention like this one, so the slot can be deleted when the PR closes:

# Naming convention: preview/<owner>/<repo>/pr-<number>-<platform>
lim asset push ./build/MyApp.app.tar.gz \
  -n "preview/${OWNER}/${REPO}/pr-${PR_NUMBER}-ios"

The action itself builds and uploads in one step through the TypeScript SDK, using the same naming convention. lim xcode build --upload "preview/…" also builds and uploads in one step; see Build with Xcode.

Upload from another process or a browser

getOrCreate (GetOrNew in Go, get_or_create in Python) returns the asset record with a signedUploadUrl; you PUT the bytes to it yourself:

const asset = await lim.assets.getOrCreate({ name: 'my-app-v1.2.3.tar.gz' });
// asset.id, asset.name, asset.signedUploadUrl, asset.signedDownloadUrl,
// asset.md5 (if an upload already exists)

if (!asset.md5) {
  const data = await fs.promises.readFile('./build/MyApp.app.tar.gz');
  await fetch(asset.signedUploadUrl, {
    method: 'PUT',
    body: data,
    headers: {
      'Content-Length': data.length.toString(),
      'Content-Type':   'application/octet-stream',
    },
  });
}

import hashlib
import requests
from limrun_api import Limrun

client = Limrun()  # picks up LIM_API_KEY from env

path = "./build/MyApp.app.tar.gz"
name = "my-app-v1.2.3.tar.gz"

with open(path, "rb") as f:
    data = f.read()
local_md5 = hashlib.md5(data).hexdigest()

asset = client.assets.get_or_create(name=name)
if asset.md5 != local_md5:
    r = requests.put(
        asset.signed_upload_url,
        data=data,
        headers={"Content-Type": "application/octet-stream"},
    )
    r.raise_for_status()

# asset.id, asset.name, asset.signed_download_url

asset, err := lim.Assets.GetOrNew(ctx, limrun.AssetGetOrNewParams{
    Name: "my-app-v1.2.3.tar.gz",
})
// asset.SignedUploadURL, asset.SignedDownloadURL, asset.Md5 (if exists)

if err != nil {
    return err
}

if asset.Md5 == "" {
    data, err := os.ReadFile("./build/MyApp.app.tar.gz")
    if err != nil {
        return err
    }
    req, err := http.NewRequest("PUT", asset.SignedUploadURL, bytes.NewReader(data))
    if err != nil {
        return err
    }
    req.Header.Set("Content-Type", "application/octet-stream")
    req.ContentLength = int64(len(data))
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
}

For browser-direct uploads, call getOrCreate on your backend, where the API key lives, and hand only the signedUploadUrl to the browser. The browser PUTs to it without touching your LIM_API_KEY or proxying bytes through your servers, which fits platforms whose end users upload their own builds.

Set an expiry

Every upload path accepts an optional time-to-live as a Go duration string: --ttl on lim asset push, ttl on getOrUpload and getOrCreate in the TypeScript SDK, --upload-ttl on lim xcode build and lim gradle build, and --asset-ttl on create --install and install-app. The asset, bytes and record, is deleted that long after the upload. The minimum is 1m; 1d is not valid Go syntax, so write 24h.

lim asset push ./build/MyApp.app.tar.gz -n my-app-v1.2.3.tar.gz --ttl 720h

The default depends on how the asset was uploaded:

• Direct uploads (lim asset push, getOrUpload, getOrCreate) never expire unless you pass a TTL. Re-uploading under the same name keeps the recorded expiry; pass a TTL on the re-upload to change it.
• Build uploads (lim xcode build --upload, lim gradle build --upload, and Bazel uploads) default to 14 days. Each build upload without an explicit --upload-ttl moves the expiry to 14 days from that upload, so actively rebuilt assets stay alive and abandoned ones get swept.

Install an asset

There are two moments to install: at instance boot, or into an instance that is already running. Both accept an Asset Storage entry (by name or ID) or a publicly reachable HTTPS URL, such as a GitHub release asset or an S3 presigned URL. URLs on your LAN do not work, because the instance downloads the file.

Pre-install at boot

Add entries to spec.initialAssets in the create call, and the device starts with the app on its home screen. On the CLI, --install <path> uploads a local file to Asset Storage first, and --install-asset <name> references a stored asset; repeat either flag for several apps.

lim ios create --install ./MyApp.app.tar.gz

const instance = await lim.iosInstances.create({
  wait: true,
  spec: {
    initialAssets: [
      // From Asset Storage by name
      { kind: 'App', source: 'AssetName', assetName: 'my-app-v1.2.3.tar.gz',
        launchMode: 'ForegroundIfRunning' },

      // From a public HTTPS URL
      { kind: 'App', source: 'URL', url: 'https://example.com/builds/123.tar.gz' },

      // By asset ID (when you already have one)
      { kind: 'App', source: 'AssetID', assetId: 'asset_01j...' },
    ],
  },
});

instance = client.ios_instances.create(
    wait=True,
    spec={
        "initial_assets": [
            # From Asset Storage by name
            {"kind": "App", "source": "AssetName", "asset_name": "my-app-v1.2.3.tar.gz",
             "launch_mode": "ForegroundIfRunning"},

            # From a public HTTPS URL
            {"kind": "App", "source": "URL", "url": "https://example.com/builds/123.tar.gz"},

            # By asset ID (when you already have one)
            {"kind": "App", "source": "AssetID", "asset_id": "asset_01j..."},
        ],
    },
)

instance, err := lim.IosInstances.New(ctx, limrun.IosInstanceNewParams{
    Wait: param.NewOpt(true),
    Spec: limrun.IosInstanceNewParamsSpec{
        InitialAssets: []limrun.IosInstanceNewParamsSpecInitialAsset{
            // From Asset Storage by name
            {
                Kind:       "App",
                Source:     "AssetName",
                AssetName:  param.NewOpt("my-app-v1.2.3.tar.gz"),
                LaunchMode: "ForegroundIfRunning",
            },
            // From a public HTTPS URL
            {
                Kind:   "App",
                Source: "URL",
                URL:    param.NewOpt("https://example.com/builds/123.tar.gz"),
            },
            // By asset ID (when you already have one)
            {
                Kind:    "App",
                Source:  "AssetID",
                AssetID: param.NewOpt("asset_01j..."),
            },
        },
    },
})

lim android create --install-asset my-app-v1.2.3.apk

const instance = await lim.androidInstances.create({
  wait: true,
  spec: {
    initialAssets: [
      // From Asset Storage by name
      { kind: 'App', source: 'AssetName', assetName: 'my-app-v1.2.3.apk' },

      // From a public HTTPS URL
      { kind: 'App', source: 'URL', url: 'https://example.com/builds/123.apk' },

      // By asset ID (Android takes a list)
      { kind: 'App', source: 'AssetIDs', assetIds: ['asset_01j...'] },
    ],
  },
});

instance = client.android_instances.create(
    wait=True,
    spec={
        "initial_assets": [
            # From Asset Storage by name
            {"kind": "App", "source": "AssetName", "asset_name": "my-app-v1.2.3.apk"},

            # From a public HTTPS URL
            {"kind": "App", "source": "URL", "url": "https://example.com/builds/123.apk"},

            # By asset ID (Android takes a list)
            {"kind": "App", "source": "AssetIDs", "asset_ids": ["asset_01j..."]},
        ],
    },
)

instance, err := lim.AndroidInstances.New(ctx, limrun.AndroidInstanceNewParams{
    Wait: param.NewOpt(true),
    Spec: limrun.AndroidInstanceNewParamsSpec{
        InitialAssets: []limrun.AndroidInstanceNewParamsSpecInitialAsset{
            // From Asset Storage by name
            {
                Kind:      "App",
                Source:    "AssetName",
                AssetName: param.NewOpt("my-app-v1.2.3.apk"),
            },
            // From a public HTTPS URL
            {
                Kind:   "App",
                Source: "URL",
                URL:    param.NewOpt("https://example.com/builds/123.apk"),
            },
            // By asset ID (Android takes a list)
            {
                Kind:     "App",
                Source:   "AssetIDs",
                AssetIDs: []string{"asset_01j..."},
            },
        },
    },
})

For the rest of the create call, such as regions, clues, timeouts, and sandboxes, see Instance spec and status. It also shows a full create response.

Install on a running instance

When a user rebuilds during a live session, push the new build and tell the running instance to install it. No restart and no reconnect are needed:

lim ios install-app ./MyApp.app.tar.gz
lim android install-app https://example.com/build.apk --id <instance-id>

// The device clients use installApp on iOS and sendAsset on Android.

// iOS: the md5 enables server-side caching, so a build already installed
// in this region skips the download.
await ios.installApp(asset.signedDownloadUrl, {
  md5: asset.md5,
  launchMode: 'ForegroundIfRunning',
});

// Android: the instance downloads the APK and runs pm install.
// The default client-side timeout is 120 s; raise it for large APKs.
await android.sendAsset(asset.signedDownloadUrl, 180_000);

CLI only: install-app accepts a local path, which it uploads to Asset Storage first with MD5 deduplication, or a URL it passes to the instance.

installApp accepts md5, timeoutMs (default 120_000), and launchMode. The Go iOS client has InstallApp too; sendAsset is TypeScript-only, and the Python SDK has no device client. From those languages, use lim ios install-app and lim android install-app, or adb install over the tunnel. Split-APK groups install only at boot. For opening device clients and the full app lifecycle, see Manage apps and Pre-install APKs.

Use Expo Go and other catalog apps

Limrun maintains a small catalog of prebuilt apps under the appstore/ name prefix. It holds Expo Go, which lets React Native users open a Snack or a local Expo project on a remote device without uploading anything, and the Maestro XCTest runner used by the Maestro integration.

Install a catalog app at boot the same way as your own assets. The appstore/ prefix is part of the name:

spec: {
  initialAssets: [{
    kind: 'App',
    source: 'AssetName',
    assetName: 'appstore/Expo-Go-55-iOS-latest.tar.gz',   // or .apk for Android
    launchMode: 'ForegroundIfRunning',
  }],
}

Pair the boot install with the openUrl prop of <RemoteControl /> to land the device on the user's Expo project on first paint:

<RemoteControl
  url={session.endpointWebSocketUrl}
  token={session.token}
  openUrl="exp://exp.host/@user/my-snack"
/>

That is the whole integration: the backend creates the instance with the Expo Go asset, and the frontend renders <RemoteControl /> with the project URL. No Expo Go upload and no build pipeline.

List the catalog to see what else is available. The server fills the result with your own assets first and gives catalog entries only the remaining slots, so filter on the appstore/ prefix to see the whole catalog:

lim asset list --include-app-store --name-prefix appstore/

const apps = await lim.assets.list({
  includeAppStore: true,
  namePrefixFilter: 'appstore/',
});

Organize assets for multiple tenants

Asset names are global to your organization. The store has no tenant scoping, no labels, and no folders; the one primitive is the name itself, queried with namePrefixFilter in the TypeScript SDK or --name-prefix on the CLI.

Put the tenant, or any stable scope such as a workspace, customer, project, repository, or PR number, at the front of the name:

acme/my-app-v1.2.3.tar.gz
acme/my-app-2026-05-18-abc1234.tar.gz
acme/my-app-pr-742.apk
globex/expo-snack-build.tar.gz

The slash is not required, but it reads well and survives any prefix scan. Pick one separator and use it across your platform.

Two common operations follow from the prefix:

// List one tenant's assets (for an admin UI or a usage dashboard)
const acmeAssets = await lim.assets.list({
  namePrefixFilter:   'acme/',
  includeDownloadUrl: true,
});

// Offboarding: drop everything a tenant ever uploaded. assets.list returns one
// batch of at most `limit` items and does not page, so repeat until it is empty.
let batch;
while ((batch = await lim.assets.list({ namePrefixFilter: 'acme/', limit: 500 })).length) {
  for (const a of batch) await lim.assets.delete(a.id);
}

The platform field splits a tenant's namespace further when one logical name covers both an iOS simulator build and an Android APK:

const list = await lim.assets.list({ namePrefixFilter: 'acme/' });
const iosOnly     = list.filter((a) => a.platform === 'ios');
const androidOnly = list.filter((a) => a.platform === 'android');
const universal   = list.filter((a) => !a.platform);

Integrations written before the field was named platform may still read os, which is returned as a deprecated alias with the same value.

List, get, and delete assets

assets.list, assets.get, and assets.delete are the calls you wire into an admin UI, a cleanup job, or an offboarding flow. List assets with a name filter, fetch one by ID, and delete it:

lim asset list
lim asset list --name my-app-v1.2.3.tar.gz --download-url
lim asset list <id> --download-url
lim asset delete <id>

const assets = await lim.assets.list({
  limit: 50,
  nameFilter: 'my-app-v1.2.3.tar.gz',         // exact match
  // namePrefixFilter: 'acme/',                // alternative; LIKE wildcards treated as literals
  includeDownloadUrl: true,
  includeUploadUrl:   false,
  includeAppStore:    false,
});

const single = await lim.assets.get(assetId, { includeDownloadUrl: true });

await lim.assets.delete(assetId);

from limrun_api import Limrun

client = Limrun()

assets = client.assets.list(
    limit=50,
    name_filter="my-app-v1.2.3.tar.gz",
    include_download_url=True,
)

single = client.assets.get(asset_id, include_download_url=True)

client.assets.delete(asset_id)

assets, err := lim.Assets.List(ctx, limrun.AssetListParams{
    Limit:              param.NewOpt(int64(50)),
    NameFilter:         param.NewOpt("my-app-v1.2.3.tar.gz"),
    IncludeDownloadURL: param.NewOpt(true),
})

single, err := lim.Assets.Get(ctx, assetID, limrun.AssetGetParams{
    IncludeDownloadURL: param.NewOpt(true),
})

err = lim.Assets.Delete(ctx, assetID)

assets.list accepts these filters:

The CLI maps these to --name, --name-prefix, --download-url, --upload-url, and --include-app-store, and adds --kind App|Keychain to filter by kind. For example, list one tenant's assets:

lim asset list --name-prefix acme/

To download an asset's file, use lim asset pull <id_or_name>.

Next steps