Connect one placement. Verify the whole release.
Start with an image in your app that changes regularly. Define its constraints and fallback, connect it to Assetlib, then verify a published replacement and rollback in the same running app.
Create a preview workspace.
- Open the Assetlib console and choose Continue with Google or Continue with GitHub. Either account needs a verified email; to accept an invitation, use the one with the invited address.
- Choose Create workspace, name it, select the optional demo images checkbox, then confirm Create & publish demo. Assetlib creates four placements (two travel images, a four-stage task illustration and a tintable icon), adds sample artwork, and publishes the first release. The console opens on the workspace’s Overview.
- Open Settings › Connect and choose your SDK, or Try a demo for the sample apps. Choose Production for the seeded release. Under Public SDK configuration, choose Download JSON, or expand View configuration and use Copy configuration.
The demo placements are a starting point. For your own app, choose and register the placement you intend to use.
The SDK configuration identifies your app and its verification key. It contains no password, private signing key, or admin token. Keep account credentials in the console.
Give one image a stable reference.
For help connecting your first image, book free onboarding.
- Choose a non-confidential image and declare its placement in the app’s
assetlib.catalog.json: a key, a width and height, and the bundled fallback. The width and height are a reference size, not a crop: they fix the aspect ratio every image for that placement must match and identify the placement. The Expo SDK sizes requests from the view; the Swift and Kotlin SDKs request the reference size unless your app passes pixels. Never renumber them to change sharpness. In an Expo app,assetlib initorassetlib adoptwrites the entry from an image the app already bundles. Keep screen behavior and layout in your app. - Install matching SDK packages using the versioned SDK instructions. Generate typed references from a checked-in placement catalog; normal app builds do not need a network request to Assetlib.
- Register the catalog from CI with
assetlib syncon every build; placements then appear on Placements as declared by that build. A product owner can Request a placement in the console before the build lands: its page shows the catalog entry to add, and it becomes declared when a build registers it. - Configure a client with the public SDK configuration and render the placement with its fallback. Add an explicit refresh action and inspect the selected image’s source and release number.
- Build and run your app on its target platforms. Confirm it still displays the bundled image before a remote image is available.
The initial integration requires development and an app release. Later compatible artwork changes can be published separately. New screens, layouts, behavior, and placement contracts still require app development.
Native integrations have separate instructions: Swift SDK preview and Kotlin SDK preview. Use the documentation that matches the installed release.
Connect your coding agent.
Assetlib’s MCP server lets a coding agent work with one workspace as you, with your role: it reads each placement’s contract, the image it shows in draft, staging and production, its code references and release history, and the workspace’s setup steps. With your permission it uploads images and assigns them to placements as a draft. It cannot publish.
- Add the server to your agent. Claude Code:
claude mcp add --transport http assetlib https://console.assetlib.dev/mcp, then run/mcpand choose Authenticate. Codex:codex mcp add assetlib --url https://console.assetlib.dev/mcp, thencodex mcp login assetlib. Claude (web or desktop app): under Customize › Connectors, choose Add › Add custom connector, enterhttps://console.assetlib.dev/mcp, then Connect. Cursor and other clients that support remote MCP servers with OAuth: addhttps://console.assetlib.dev/mcp. - Sign in to the console in the browser window that opens, choose the workspace, and choose whether the agent may draft changes. A viewer’s connection is read-only.
- Ask the agent, for example, “Set up Assetlib in this app with the assetlib MCP server” or “What does each placement on the Discover screen show in production?”
Publishing stays in the console: the agent’s review_draft tool returns the link for a person with publish rights. Disconnect an agent under Settings › Profile. Reading a workspace over MCP is free; an agent’s uploads count toward storage like any upload.
Its tools: get_workspace, get_setup_guide, list_placements, get_placement, list_images, get_image, list_releases and review_draft read; create_image_upload and assign_image change the draft and need a connection that allows draft changes.
- “This connection is read-only.” Connect again and keep Upload images and assign them to placements as a draft ticked. A viewer can only read.
- “No placement named …” Placements come from the app’s
assetlib.catalog.json; runassetlib syncafter adding one. - “Choose an image with the placement’s aspect ratio.” Pick or upload an image whose width and height have the placement’s ratio.
- An upload link fails. Each link works once for 15 minutes; send the file’s bytes with its
Content-Type, or ask for a new link.
The assetlib plugin for Claude Code and Codex in AssetLib/agent-plugins adds the same server with a skill that explains its tools.
Publish a different image.
Prepare a visibly different replacement that matches your placement’s aspect ratio, at any size within the upload limits. Check its crop and fit in the actual component.
- On Images, drop a still PNG, JPEG, WebP, or a supported static SVG, or choose a file. Assetlib keeps the original and prepares sizes for delivery: PNG and lossless WebP for artwork, compressed WebP for photos. Web can use the normalized SVG; native apps use raster versions.
- On Placements, assign the uploaded image in your connected placement’s row, or open the placement for its states and variants. States are named images that publish together: your app picks which one to show, and a release never mixes states from different publications.
- Choose Publish release. Under Publish to, choose Staging and production, then confirm Publish release. If your workspace requires approval for production, publish to staging, then on Releases choose Approve and Promote.
- Refresh your app’s client, then open the placement’s screen. Confirm the replacement is displayed and record its release number and source.
A device shows the new image only after your app refreshes and downloads it, so check the screen as well as the console.
Published artwork is public. Only publish images you are comfortable making available through delivery links. Editing your workspace requires sign-in.
Raster inputs are limited to 4 MiB and 20 megapixels; SVG has additional format limits. Each prepared image may be up to 8 MiB. Each workspace has a storage quota, 1 GiB by default, counting originals, prepared sizes and animations; the console shows usage and warns at 90%. Updates need a successful refresh and download.
Restore an earlier version.
- Open Releases in the console and find the earlier publication under Production.
- Choose Restore on its row, then confirm Restore and publish.
- Refresh the client again and return to the placement’s screen. Confirm the earlier artwork is displayed with the new release number.
Rollback publishes the earlier content with a new release number. It preserves the release history and leaves your draft placement bindings unchanged. The release number an app reports is the console’s production publication number. A placement the restored release does not include goes back to the app’s bundled image once the app refreshes, on JavaScript/Expo 0.7.0-preview.1 and Swift and Kotlin 0.6.0-preview.1 or later; earlier SDK versions keep an image they already downloaded for it until a release publishes the placement again.
Record what the app actually displays.
- Record the installed app build, SDK version, placement key, current image, and selected release.
- Publish a visibly different compatible image. Refresh the same running app and capture the replacement, its source, and its release number.
- Restore the earlier version in the console. Refresh again and capture the earlier image under a newer release number.
- Disable networking and restart the app. Confirm it renders an eligible verified cached image or its bundled fallback. Also check a fresh installation offline, where only bundled artwork is available.
Run these checks on each platform you intend to ship. Note a fallback or a failed download separately from a successful delivery. A source-selection callback tells you which image the app chose, not that anyone saw it.
Optional: turn on usage reporting in the JavaScript SDK (telemetry: { enabled: true, build: … }; off by default) so Placements shows what each build resolves and displays. It sends placement keys, counts and a random install ID, never user or device identifiers, and it changes your app’s data collection, so review your store privacy disclosures first. Settings › Connect in the console shows the option.
Before you ship: the SDKs, JavaScript/Expo 0.7.13-preview.1, Swift 0.7.0-preview.1 and Kotlin 0.6.0-preview.1, are developer previews, and there is no production SLA yet. Keep essential artwork bundled and run the checks above in your own app.
What the SDKs support: all three follow a staging environment, resolve light and dark variants and experiment arms (your own experiment tool picks the arm), draw tintable icons your app colors when it draws them, and play short, muted, looping clips with a poster, fetched only when your app asks; Android apps supply the player. Named states, paginated catalogs, and opt-in usage reporting are in the JavaScript SDK only. The JavaScript SDK resolves verified Lottie JSON for a player your app supplies; Swift and Kotlin apps show the animation’s still poster, and native playback is planned. The compatibility table gives the first version of each SDK with each feature.
Developer previews: install the Figma plugin from Figma Community to insert Assetlib artwork into Figma and send a selected node to a placement as a draft. Publishing stays in the console. Build sync registers your placement catalog with assetlib sync, checks generated references, and previews Expo adoption; install @assetlib/cli 0.4.9 from npm (preview tag) or the tarball attached to GitHub release v0.7.13-preview.1.
Still planned: usage reporting from the Swift and Kotlin SDKs, and hosted usage billing.
Use the sample apps to test delivery.
Roam, the travel demo, and Daylight, the to-do demo, are small open-source apps we built with bundled artwork and the SDK already integrated. They are the same apps that run live on the homepage, beside Still, a focus timer that carries twelve bundled scenes and has no runtime connection. They are integration references, not customer deployments.
In Roam or Daylight, open Connect, paste the console’s public JSON into Public SDK configuration, and choose Connect and check release. After publishing or restoring artwork, choose Check for updates and inspect the relevant screen.
The seeded travel.coast and travel.ridge placements use 4:3 images, such as 1200 × 900 px. The seeded tasks.garden placement uses 3:2, such as 600 × 400 px.
- SDK source and installation — typed references, signed delivery, cache, and fallback behavior.
- Travel demo source and to-do demo source — Expo integration references.
- iOS demo source — a SwiftUI integration reference.
- Android demo source — a Compose integration reference.
The MIT-licensed SDK previews are available on GitHub. Follow each repository’s installation instructions and use matching versions. JavaScript SDK packages are on npm under the preview tag and attached to versioned GitHub releases. The read-only asset audit is on npm as @assetlib/audit and as the assetlib-audit plugin for Claude Code and Codex.
To install the plugin in Claude Code, run claude plugin marketplace add AssetLib/agent-plugins, then claude plugin install assetlib-audit@assetlib. In Codex, run codex plugin marketplace add AssetLib/agent-plugins, then codex plugin add assetlib-audit@assetlib; the first command only adds the marketplace, and the second installs the plugin. For Cursor, GitHub Copilot and other agents the skills CLI supports, run npx skills add AssetLib/agent-plugins --skill assetlib-audit to install the same skill.
Know the limits, and what an app does at one.
The hosted console and its delivery routes count requests per IP address, in fixed one-minute windows that start on the minute (one hour for creating a workspace). The counters hold a keyed hash of the address, not the address itself.
- 180 requests a minute
- Everything one address sends to the console and its API: signed-in console use, manifest and image downloads, and requests made with an app token, such as
assetlib syncin CI and the Figma plugin. - 20 a minute for sign-in
- Sign-in, session checks, and sign-out, which also have the per-step limits below.
- 12 uploads a minute
- Image and Lottie animation uploads.
- 60 usage reports a minute
- Batches from the JavaScript SDK’s opt-in usage reporting.
- 30 a minute for invitation links
- Opening and accepting an invitation.
- 3 new workspaces an hour
- Creating a workspace.
Sign-in also has limits per address for each step: 10 for starting a sign-in, 15 for the return from GitHub or Google, and 120 each for session checks and sign-out. Each count resets only after a full minute with no allowed request.
A request over a limit gets status 429 with the JSON body {"error":"Too many requests. Please try again shortly."}, Cache-Control: private, no-store, and no Retry-After header; retry after the current minute. A 429 from a per-step sign-in limit instead carries the same message as both error and message, with "code":"AUTH_REQUEST_FAILED", and a Retry-After header in seconds.
What the SDKs do at a limit
No SDK refreshes on a timer or retries a failed refresh on its own: your app decides when to call refresh. When the manifest request fails, with a 429, another error status, a timeout, or no network, refresh returns the error with the last accepted release number and keeps that release. Each placement that release publishes keeps showing the newest verified image already on the device, from that release or an earlier retained one, and otherwise its bundled fallback; a placement the current release does not publish shows the bundled image on the SDK versions named under Restore. A failed image download falls back the same way. This is the behavior of the JavaScript and Expo, Swift, and Kotlin SDKs.
The JavaScript SDK’s usage reporting keeps unsent counts and sends them again at its next attempt, every 60 seconds by default; reporting never changes what renders. assetlib sync prints the status and message and exits with code 1, so the CI step fails and can be run again.
Limits as of October 10, 2026; they can change. They protect the preview’s cost and stability and are not a capacity commitment.
Keep Figma and the app on the same art.
The Assetlib plugin in Figma Community puts your app’s placement art on the canvas and sends a selected layer back to a placement as a draft. Publishing stays in the Assetlib console. Assetlib is in developer preview.
- Placement
- An image your app’s code declares in its catalog, with a key such as
home.bannerand a reference size. The plugin lists placements; it never creates them. - Cell
- One image of a placement: a state, an appearance (light or dark), and an A/B arm, when the placement declares them. A cell without its own art shows the art it inherits from another cell, as the app would.
- Environment
- Draft is unpublished art and the only thing the plugin changes. Staging and Production are the releases published for testing and for your app’s users. Insert shows Production, or Draft until Production has a release, unless you choose another.
- Open the plugin. Open the Assetlib listing in Figma Community and choose Open in Figma. Sign in to Figma if asked, then use Open in… to choose a design file or New file. You can open Assetlib again from Figma’s Plugins menu.
- Connect. Choose Connect to Assetlib. Your browser opens the console: sign in, check that the page shows the code the plugin shows, choose the workspace, and approve. You need edit access (editor, publisher, or owner). A workspace owner can instead create a Draft token under Settings › Tokens for Use a token instead. A Figma access token is neither needed nor accepted.
- Insert. On Insert, each placement shows its art in the placement’s proportions, the last part of its key, and one chip, such as 2 behind (linked layers show older art), On this page, or In this file. Choose a placement and pick its cell in the footer’s strip, a row for each state and a column for each appearance in each A/B arm, or choose an image from the library. Then choose the footer’s button or drag the row onto the canvas. The selection decides what happens: nothing selected makes a new layer at the reference size divided by the 1×, 2×, or 3× you choose; a frame with layers inside takes the art inside it, fitted to the frame and never larger than the reference size; empty shapes and frames are filled; and a linked layer that shows an image has its image replaced. On an instance of an Assetlib placement component, Replace in component changes the main component so every instance follows; it never overrides the instance. Placement art arrives as a component whose description tells coding agents the image is data-supplied: they render it with the app’s generated accessor instead of a downloaded file, and download it only as the bundled fallback of a placement not yet in the app’s catalog.
- Send. Select one layer, open Send, choose a placement and cell, and choose Send to draft. If asked, paste this Figma file’s link and choose Link file to continue the send. Placements that fit the layer’s ratio come first. The layer’s aspect ratio must be within 2% of the placement’s; Match ratio keeps the width and sets the height. The PNG it exports is up to 3× the layer’s size, capped at 2048 px on the long edge and at the native resolution of the sharpest image in the layer.
- Sync. Inserted and sent layers stay linked to their cell, and selecting one shows the Sync bar. Sync to draft (or Cmd+Enter) sends your later edits to that cell’s draft, replacing the layer’s earlier sends wherever Draft uses them.
- Update. When the layer’s environment has different art now, after a newer release, a restore, or a teammate’s send, the Sync bar offers Update. It puts that art in the layer and keeps its crop, size, and position, as one undo step. It works on a layer that shows an image, one layer at a time.
- Find linked layers. In this file, beside Placements and Images, lists the layers linked to this app, grouped by page and top-level frame, and marks the ones that are behind. Choose one to select it on the canvas and use its Sync bar. A file with several pages starts with this page; Include all pages adds the rest. Scanning changes no artwork.
- Publish in the console. The Sync bar says whether the layer’s art is in Production, in Staging only, or in Draft only. Open in console opens the placement there to review the draft and publish it.
The plugin authenticates with its draft token and sends the PNG you choose to export with its Figma file and layer identifiers, layer name, export settings, and chosen placement. Links on layers are plugin data that travel with the file and never hold the token. See the privacy notice for data handling.