Quickstart

arcy init scans your codebase, wires up ARCYProvider, and generates the .arcy/ Application Knowledge Graph: the structured YAML files ARCY uses to understand your product. It does not touch your JSX. Element-level detail (what's on each page, and the elements Copilot and Autopilot can act on) builds up on its own from real usage once the SDK is live. See Element Targeting for how that works.

Step 1: Add your keys to .env

Get your keys from the ARCY dashboard under Apps > [your app] > API Keys.

Add to .env.local:

NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY=pk_live_...
ARCY_SECRET_KEY=sk_live_...

Both keys are required. The CLI reads them from your env file automatically.

Step 2: Install and run

npmpnpmbunyarn

npm install -g @arcyai/sdk
arcy init

pnpm add -g @arcyai/sdk
arcy init

bun add -g @arcyai/sdk
arcy init

yarn global add @arcyai/sdk
arcy init

The CLI detects your framework, wires up ARCYProvider, and runs arcy analyze once to seed your .arcy/ knowledge graph with your app's routes.

Everything here is local: zero network calls except installing the package itself.

Then push your configuration:

arcy push

Step 3: Verify locally

Start your dev server. The ARCY widget mounts open in the chat view, bottom-center, by default — there's no closed launcher bubble to click first unless you explicitly opt into one via customization.theme.initialPosition (see Customization).

If the widget does not appear, check your browser console for errors. The most common cause is a missing or incorrect public key.

Local development works with zero extra setup: arcy init wires up your app, but nothing checks that localhost is a "verified" origin. The backend allow-lists every common dev-server port (3000-3010, 5173, 4200, 8080) by default, in every environment, so your SDK calls work from the moment your dev server starts.

Step 4: Verify your production domain

This step is required before real users see ARCY — an unverified origin can never bootstrap a session or pass CORS. Unlike local development, your production domain does not verify itself. Verifying alone does not put ARCY live; you also need to deploy your app (Step 5).

1. In the dashboard, go to Manage > Settings > Verified origins and add your production origin (for example https://myapp.com).
2. ARCY shows you a DNS TXT record to create: name _arcy-verify.myapp.com, value a generated token.
3. Add that record with your DNS provider. Propagation is usually fast but can take a few hours depending on your provider's TTL.
4. Once it's live, click Verify in the dashboard.

Verifying https://myapp.com also verifies https://www.myapp.com (and vice versa) — the only exception to exact-hostname matching. Any other subdomain (app.myapp.com, staging.myapp.com) needs its own separate origin and its own DNS TXT record. See Domain verification & session trust for the full mechanism.

Step 5: Deploy to production

Everything so far is local. ARCY only reaches real users once your app is deployed with the integration in place.

1. Commit the changes arcy init made: the ARCYProvider wiring and the .arcy/ directory.
2. Set NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY in your production environment (your host's env settings, for example Amplify, Vercel, or your container config). Vite/CRA projects also need the framework-specific duplicate from the table below. ARCY_SECRET_KEY is only needed where you run arcy push (your machine or CI), not in the runtime environment.
3. Deploy to your live site.

Until you deploy, ARCY runs only in your local or preview build. After deploy, load your production site as a real user would: the widget appears once the session bootstraps against your verified origin.

Framework-specific env vars

NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY is the one name the CLI itself always checks for (arcy init's preflight, plus push/pull/status/log), regardless of framework, and it's what a Next.js app's ARCYProvider reads directly. Vite and CRA never expose NEXT_PUBLIC_-prefixed vars to the browser — only their own convention — so those two frameworks need the same publishable key value duplicated under a second name:

arcy init detects your framework and prints a reminder naming the exact var to add when it isn't Next.js. ARCY_SECRET_KEY has no framework-specific variant — the CLI is the only thing that ever reads it, never the browser.

What to expect during init

Framework detection

The CLI first detects your project setup:

  Detecting project
  ✓ Framework:  Next.js (App Router)
  ✓ Auth:       @clerk/nextjs
  ✓ Entry:      src/app/layout.tsx
  ✓ TypeScript: true

Fully supported and auto-wired: Next.js App Router, Next.js Pages Router, Vite + React, and Create React App, each with Clerk, NextAuth, Auth0, Supabase, or Firebase.

Any other framework or auth setup still gets a full arcy analyze run; init prints a manual ARCYProvider snippet for you to paste instead of wiring it automatically.

The generated wrapper

arcy init writes a small arcy-provider wrapper component next to your app entry. Its live JSX stays minimal on purpose: your publishable key, showWidget={true}, and any props your own app forwards through it.

Above that live JSX, the wrapper includes a commented-out reference block showing the full prop and customization shape — theme, elements, limits, modes, content — with labeled placeholder values, plus a framework-appropriate onNavigate snippet. Uncomment and fill in whatever you need; nothing in that block ever ships as a live default you'd have to notice and change. See Configuration and Customization for the full field docs.

Local analysis

arcy init wires ARCYProvider with a deterministic codemod, then runs arcy analyze once: an AST (Abstract Syntax Tree) walk (a static read of your code's structure) that finds your routes and generates .arcy/ YAML skeletons, plus a day-one navigation seed read from your framework's own route configuration.

Nothing is transmitted; this step makes zero network or LLM calls. It never writes into your JSX.

  Analyzing
  ✓ Wired ARCYProvider in src/app/layout.tsx
  ✓ Seeded navigation from 6 routes
  ✓ Generated .arcy/app.yaml and 6 route files

Element-level knowledge graph content (what's on a page, and the elements Copilot and Autopilot can act on) is not generated here. It builds up from real usage once the SDK is live, curated by ARCY's AI, and never goes live to Copilot/Autopilot without either accumulated trust or your explicit confirmation. See Element Targeting.

Monorepo prompt

If you already know your target app, run arcy init from inside it, or point --dir at it directly, for example arcy init --dir apps/dashboard. The .arcy/ knowledge graph is written to that app directory, not the monorepo root.

If you run arcy init at the root of a pnpm workspace instead (a directory containing pnpm-workspace.yaml), the CLI detects that before it even looks at your framework and asks which app to set up:

  This looks like a pnpm workspace root.
  Which app are you setting up?
    1. apps/dashboard
    2. apps/landing
    3. Other (enter path manually)

  ? Select (1-3):

Everything after that runs scoped to the app you pick, never the workspace root, even if the root's own package.json happens to list a framework dependency for shared tooling.

What's next

• CLI commands: use arcy analyze, arcy push, and arcy status as your integration grows
• Configuration: all ARCYProvider props
• Customization: the full customization shape (theme, elements, limits, modes, content)
• AI modes: how Chat, Copilot, and Autopilot work
• Troubleshooting: fixes for common setup errors, including the widget not appearing in production