# Connect your app (/docs/start/existing-app)



Use this when you already have a website or app and want to add quests, points and rewards to it, such as a quiz on your launch page or points for posts on X, without moving anything. Your app keeps its design, its login and its hosting.

Your developer or coding agent runs these steps. At the end, members sign in with the login they already have, complete a quest that Domino checks and records, and keep their progress after a refresh.

To start, create or select a project in [Console](https://console.domino.run) using the existing-app path, and open your own repository in your editor. You do not need a Domino-hosted repository.

## 1. Install and connect [#1-install-and-connect]

Use your app's package manager. With npm:

```sh
npm install @domino-sdk/relay@latest
npm install --save-dev @domino-sdk/relay-cli@latest
npx domino login
npx domino init --project YOUR_PROJECT
npx domino agents install
npx domino doctor --remote --json
```

Run these commands in the package that will use Domino.

| Command                  | What it does                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `domino login`           | Connects the CLI once you approve it in Console. The CLI saves its credential automatically.                                          |
| `domino init`            | Creates `relay.json` and `RELAY.md`. It does not create sample quests or change your framework. Commit those files and your lockfile. |
| `domino agents install`  | Registers skill loaders that read the project-local CLI's guidance and adds marked pointers to project instructions.                  |
| `domino doctor --remote` | Verifies the configuration.                                                                                                           |

During `login`, your agent sends the code first, followed by the sign-in link. Copy the code, open the link, and enter the code in Console to approve the CLI connection. Leave the command running until it confirms success, and keep credentials out of chat. The code works for 15 minutes, and the connection page shows the minutes left; after that, run `domino login` again for a new code. The page also shows when, from which country and by what client the request was made: approve only a code your own terminal just showed.

If you are signed out of Console, sign in or create an account first. Console returns you to the same CLI connection page so you can enter the terminal code.

Replace `YOUR_PROJECT` with the identifier from Console, or omit `--project YOUR_PROJECT` to choose an accessible project interactively.

> [!DEV]
> Scripts should pass an explicit project and `--json`; use `--no-interactive` to disable prompts while keeping readable output.
>
> The skill loaders read the installed CLI package in `node_modules`. After upgrading the CLI, ask the agent to re-read that skill; you do not need to reinstall guidance. Run `domino doctor --json` if the package or loaders appear to be missing.

> [!WARNING] Existing connection files are never overwritten
> If connection files already exist, inspect them before running init. The command refuses to overwrite them. The skill installer migrates known copied guidance but stops on customizations before changing any selected files. Preserve custom rules in AGENTS.md and follow the [migration procedure](/docs/reference/existing-app).

## 2. Give your agent a task [#2-give-your-agent-a-task]

> [!PROMPT]
> Use the Domino skill. First ask for any missing campaign goal, audience, desired actions, and reason to participate, then wait for my answers. Inspect this app and propose a campaign brief and the smallest integration that fits it. Wait for my campaign confirmation before adding a community quest. Keep our existing design, components, and deployment process. Check the capability map before choosing rewards. Verify the flow through our app and explain anything I need to configure in Console.

Your existing app supplies the design. The agent asks about campaign details, without requiring brand discovery, a website reference, or visual approval.

The [existing-app integration reference](/docs/reference/existing-app) gives agents the detailed workflow.

> [!TIP] SDK behaving unexpectedly?
> If the installed SDK behaves differently from the docs or server, check the [changelog](/docs/reference/changelog) and [upgrade guidance](/docs/reference/troubleshooting#check-for-an-sdk-upgrade).

## 3. Choose how people sign in [#3-choose-how-people-sign-in]

If your app already has a login, connect it so people do not need to sign in twice. Your server verifies the existing session; Domino recognizes that user and records their progress. Follow [Use your app's login](/docs/build/app-login).

```mermaid
sequenceDiagram
    actor Person
    participant App as Your app
    participant Server as Your server
    participant Domino
    Person->>App: Sign in with your login
    App->>Server: Request with session
    Server->>Domino: Verified user
    Domino-->>App: Quests and progress
```

If you are building a new Domino-hosted app, its member sign-in is already part of that path. Management login in the CLI is separate from member sign-in.

## 4. Publish behavior and try the app [#4-publish-behavior-and-try-the-app]

Your agent adds quest modules as `quests/**/*.quest.ts` files, which the discovery patterns `domino init` wrote to `relay.json` find without listing each one. Preview the deployment, then publish it to test:

```sh
npx domino deploy --preview --environment test --json
npx domino deploy --environment test --json
```

| What                       | How                                                                  |
| -------------------------- | -------------------------------------------------------------------- |
| Validate settings          | `deploy --preview` checks the effective settings without publishing. |
| Publish Domino behavior    | `deploy`                                                             |
| Run and deploy the website | Your existing scripts and hosting provider.                          |

Sign in through your app, complete the quest, and confirm that progress survives a refresh.

> [!NOTE] Doctor does not test your login
> A successful doctor check verifies configuration, not your app's login or member flow.

## 5. Call Domino from your backend [#5-call-domino-from-your-backend]

Backend code that awards points, sends tracker records, or pauses trackers needs a management credential. Use a service key: an organization admin creates it in Console, and it belongs to no person, so it keeps working when the person who set it up leaves.

1. In Console, open **Settings → API keys** in the project and environment the backend uses, and find **Create a service key**.
2. Name the key, select only the **Permissions** the backend needs, and leave **Expiry** at **Never expires** unless your policy requires one.
3. Select **Create service key**, then **Copy key**. Save it in the backend's secret store as `DOMINO_MANAGEMENT_KEY`. It is shown only once.

```ts
import { createManagementClient } from "@domino-sdk/relay/server";

export const management = createManagementClient({
  baseUrl: "https://relay.domino.run",
  getToken: async () => process.env.DOMINO_MANAGEMENT_KEY ?? null,
  organization: "YOUR_ORGANIZATION",
  project: "YOUR_PROJECT",
  environment: "live",
});
```

| What        | How a service key behaves                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scope       | One project and environment. Requests for any other answer 403 `scope-mismatch`.                                                                      |
| Permissions | The ones chosen at creation, never **Access**. It cannot approve live publication, manage test members, or create keys.                               |
| Audit       | Point entries and audit records name it as `service:<key ID>`. Creating, rotating and revoking it appear under **Audit history → Access & API keys**. |
| Expiry      | None unless chosen at creation. Each secret shows its expiry and when it was last used.                                                               |

To rotate a key without downtime, select **Add secret** on it, save the new secret everywhere the backend runs, and deploy. Both secrets work in the meantime. Once the old secret's **Last used** time stops changing, select **Revoke**, then **Revoke secret** on it. **Revoke** on the key itself stops every secret at once.

Only an organization admin signed in to Console can create, rotate or revoke service keys. [Access](/docs/concepts/access#kinds-of-credentials) compares service keys with the other credentials, including what each may do in live.

> [!DEV]
> In code, an admin's Console session reaches the same operations through `management.serviceKeys`.