Your first integration

Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.

Five steps from an empty repository to a previewable integration.

1. Create the repository

Bash
JSON

curl -X POST 'https://api.eu1.luigisbox.ai/distribution/v1/repositories' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": "lbo_r2vn8c",
    "name": "example.com storefront",
    "channel_id": "lbn_4hj9tv",
    "channel_name": "example.com"
  }'

{
  "repository_id": "lbdr_8w3k2p",
  "organization_id": "lbo_r2vn8c",
  "name": "example.com storefront",
  "state": "active",
  "git_url": "https://git.eu1.luigisbox.ai/lbo_r2vn8c/lbdr_8w3k2p.git",
  "loader_script_url": "https://cdn.eu1.luigisbox.ai/b/lbdr_8w3k2p/loader.js",
  "created_at": "2026-09-03T10:12:44Z",
  "updated_at": "2026-09-03T10:12:44Z"
}

Pass channel_id and channel_name now rather than later. The channel is what the integration reads, and its name — usually the site’s domain — is written into the repository’s own agent instructions, so an agent knows which site it is working on.

Wait for state to be active. provisioning means the seeding has not finished; the repository cannot be cloned until it has.

loader_script_url is the URL your site will eventually load. It answers 404 until the first release.

2. Clone it

Git operations authenticate with your Luigi’s Box credentials — there are no SSH keys and no separate repository password.

For interactive use, install git-credential-oauth (git 2.45 or newer for silent refresh) and configure it for your region. The first operation opens a browser to sign in; after that it is silent.

git clone https://git.eu1.luigisbox.ai/lbo_r2vn8c/lbdr_8w3k2p.git example-com
cd example-com
git branch -r        # origin/main  origin/testing

Pass a directory name: without one, git clone names the checkout after the repository ID, lbdr_8w3k2p.

For CI and other machine callers, pass a token as the HTTP Basic password — the username is ignored:

git clone "https://oauth2:$LBX_TOKEN@git.eu1.luigisbox.ai/lbo_r2vn8c/lbdr_8w3k2p.git" example-com

3. Set it up

yarn setup

That installs dependencies, pulls the discovery library submodule, and materialises the skill pack into .agents/skills/. Run it before you point an agent at the repository: the repository’s instructions link into that directory.

Then start the dev server:

yarn dev

Open your real site with ?_lbx_env=development appended. The loader picks up your local build instead of the published one, so development runs against your real pages and catalog data.

4. Tell your agent to integrate

Open the repository in your coding agent and ask for what you want:

Integrate search and autocomplete on this site.

The repository’s AGENTS.md — and CLAUDE.md, for Claude Code — explains the layout, the rules and where the skill pack is; the agent reads them at the start of the session. /integrate runs the whole job; an agent picks it for “integrate our site” or “search looks wrong”.

The agent measures your existing pages, sets the channel and an app config so the integration switches on, builds the widgets against your markup, and records what it found in memory/.

Repository layout

Path
`integration/`	Yours. All integration work happens here
`memory/`	Yours. The durable record of this site — measurements, catalog facts, decisions. Readable without an agent
`.agents/local/`	Yours. Rules true for this site only, which override the skill pack
`.agents/skills/`	Generated by `yarn setup`. Edits are lost on the next run — a wrong skill gets fixed upstream
`luma/`	The shared library, as a submodule. Read it, never edit it
`.lbx/repo.json`	The repository’s identity, written when it was provisioned

Use .agents/local/ for rules that hold for your site only — your CSP, your platform, a quirk of your markup. It is never overwritten.

5. Push, preview, release

git switch -c search-widget origin/main
git push origin search-widget

The push builds, and the branch becomes loadable on your real site at ?_lbx_env=search-widget. Send that URL to whoever reviews the work.

Merging to main releases it — see Previews and releases.

Where the repository starts

A fresh repository is inert: it has no app configuration, so the integration does not start, and logs why. There is no skeleton to fill in. It starts once a configuration is added, which is the first thing /integrate does.