# create-agents24-app

Last Updated: 2026-09-07

Create a canonical Agents24 React application:

```bash
npm create agents24-app@latest
```

Create an app with an official Agent template:

```bash
npm create agents24-app@latest my-agent -- --starter customer-support
cd my-agent
agents24 prepare ./agents24
agents24 plan ./agents24
agents24 apply ./agents24
agents24 status ./agents24
agents24 publish ./agents24
agents24 status ./agents24
pnpm dev
```

Use `--starter deep-research` for the Planner/Researcher/Critic template, or omit
`--starter` to generate the scaffold without an Agent package. The old
`--starter rag` value is intentionally rejected.

The generator fetches the active compatible catalog and downloads only the selected immutable Package V2 archive. It verifies the advertised size and SHA-256 before extracting an editable `agents24/` tree with a fresh package identity. `customer-support` contains the Support Agent and empty reranked RAG foundation; `deep-research` contains the bounded Planner, Researcher, and Critic architecture with the same optional knowledge foundation. Templates never ingest content or configure credentials. `setup` combines apply, publish, and application configuration.

Choose a server-backed BFF (default) or direct client deployment. BFF offers Next.js (default) or Vite + Hono; direct client uses Vite. The Agent starter is an independent choice. Then paste a preset code from [shadcn/create](https://ui.shadcn.com/create). Soft preset `b2D1FHzlY` is the canonical default.

```bash
npm create agents24-app@latest my-app -- --integration bff --stack nextjs
npm create agents24-app@latest my-app -- --integration bff --stack vite-hono
npm create agents24-app@latest my-app -- --integration client-deployment
```

`--stack` accepts `nextjs`, `vite-hono`, or `vite`; invalid integration/stack combinations fail before generation. `--yes` now defaults to BFF + Next.js, replacing the old direct-client default. Existing Hono apps remain supported by lifecycle commands, including apps without `agents24.stack` metadata; generation does not migrate them.

The normal flow does not ask for an API base URL. Generated apps use `https://api.agents24.dev`; `--base-url` remains an advanced override for localhost, staging, private deployments, or proxies. Direct mode wires public deployment authentication through the browser session controller. BFF mode exposes a Guest host-identity adapter for customer-owned identity and login/logout navigation.

Generation does not require a deployment ID, Agent ID, or API key. `agents24 setup` detects the generated app and configures its selected integration. Direct-client mode retains `VITE_AGENTS24_DEPLOYMENT_ID`; BFF writes only the server-only `AGENTS24_API_KEY` and `AGENTS24_AGENTS` selectors and uses no deployment. The generator creates `SESSION_COOKIE_SECRET` for the default signed guest session, and setup preserves it. Generated BFFs use draft runtime locally and published runtime in production; direct clients are published-only. Use `--no-write-env` to configure platform values later.

Generated apps own their Shadcn component source, while `@agents24/client`, `@agents24/react`, and `@agents24/chat-react` provide the hardened runtime, state, streaming markdown, and MCP security behavior. Run `pnpm --filter create-agents24-app materialize:fixture` to create a disposable local fixture from the same canonical source used by the generator.

The generated scaffold uses canonical ordered `message.parts` and the default `AgentResponseTimeline`. Customize `components.Timeline` to reorder copied parts, compose the package part primitives, or render a fully custom timeline. Do not mutate canonical parts or fork the scaffold transport/runtime lifecycle.

For example, keep the package renderer but change its display order:

```tsx
import { AgentResponseTimeline } from "@agents24/chat-react/ui";
import type { Agents24ChatTimelineSlotProps } from "@agents24/chat-react/scaffold";

function Timeline({ parts, ...props }: Agents24ChatTimelineSlotProps) {
  return <AgentResponseTimeline {...props} parts={[...parts].reverse()} />;
}
```

Or fully replace it by mapping copied `parts` and rendering `AgentChatPart` (or
your own controls) with the supplied HITL callbacks. The generated app README
points to the same canonical scaffold and package guidance.

## Maintainer development

The stack-selection change is implemented in source and awaits canonical package publication and actual Vercel qualification. Do not assume the currently published `latest` contains it until release receipts confirm that version.

## Hosting

Next.js uses Node 22/24, builds without runtime credentials, and starts with the generated `build`/`start` scripts on Vercel, Railway, Render, or another Node host. For containers, enable `output: "standalone"` in `next.config.ts` before building; package `.next/static` and any `public` assets with the standalone server. Its nonce-based CSP requires dynamic, non-cached HTML. Browser BFF requests stay same-origin and credentials remain server-only.

Vite + Hono keeps its Node-server deployment. It does not generate a Vercel serverless adapter. Set host environment variables separately: `agents24 publish` publishes Agent resources, and `setup` configures the local app; neither deploys your website or sets up Artifact hosting.

## Local package development

From the repository root, `pnpm dev:agents24` incrementally prepares the current coordinated package train, publishes it to an ephemeral loopback registry, launches this packed interactive CLI, installs the selected app, and starts it. To refresh an existing isolated generated app after every package source or version change, use `pnpm dev:agents24 -- --serve /absolute/path/to/app`; it force-reinstalls that app. Use `pnpm dev:agents24 -- --template customer-support` or `--template deep-research` to generate and set up an official template against the platform catalog. Set `AGENTS24_BASE_URL` when targeting a local backend. Unchanged tarballs, scans, and packed runners are reused from the bounded development cache; add `--fresh` for a clean rebuild.