Connect your 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 using the existing-app path, and open your own repository in your editor. You do not need a Domino-hosted repository.

Install and connect

Use your app's package manager. With npm:

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.

Give your agent a task

Prompt for your agent

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 gives agents the detailed workflow.

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.

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.

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:

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.

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.

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

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 compares service keys with the other credentials, including what each may do in live.