---
title: Your first integration
description: Create an integration repository, clone it, install the skill pack, and hand the job to your coding agent.
slug: distribution/quickstart
docKind: guide
hub: luigisbox-ai
---

Five steps from an empty repository to a previewable integration.

:::note[Before you start]
You need an **organization ID** and a **channel** whose catalog already has data indexed —
the integration is built against real results, so an empty catalog gives an agent nothing
to work with. See [Feeds](/indexing/feeds/) or the
[Content API](/indexing/content-api/), and confirm with
[catalog metadata](/indexing/catalog-metadata/) that objects are there.

You also need a token for the `https://api.<region>.luigisbox.ai/distribution` audience —
see [Server-to-server tokens](/authentication/server-to-server/).
:::

## 1. Create the repository

:::hub[Config → Front-end Integration → Create Repository]{path="/frontend-integration"}
Takes a name and provisions the repository under the organization you have selected, then
offers its clone URL and loader script URL to copy. It does not record a channel, so an
agent working in a repository created this way asks which site it is for.
:::

```bash
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"
  }'
```

```json
{
  "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`](https://github.com/hickford/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.

```bash
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:

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

## 3. Set it up

```bash
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:

```bash
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:

```text
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.

:::caution[Never commit a secret]
The publishable key (`pub_…`) is not a secret and is meant to appear in the built script.
Everything else — client secrets, tokens, passwords — must stay out of the repository. See
[Browser tokens](/authentication/browser-tokens/) for which credential belongs where.
:::

## 5. Push, preview, release

```bash
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](/distribution/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.

## See also

- [Previews and releases](/distribution/previews-and-releases/) — branches, preview URLs, releases
- [Repositories API](/distribution/repositories-api/) — the endpoints in full
- [Sending events](/analytics/sending-events/) — what the integration reports, and why it matters