@camelai/create-run-app 0.0.0 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qaml-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
 # @camelai/create-run-app
 
-Placeholder. The first release is 0.11.0, from https://github.com/qaml-ai/run.
+Create a Next.js app with a streaming chat to an agent on camelRun:
+
+```sh
+npm create @camelai/run-app my-app -- --api-key $CAMELAI_API_KEY
+cd my-app && npm run dev
+```
+
+Options: `--api-key` (default: `CAMELAI_API_KEY`), `--base-url` (a runtime other than
+https://agents.camelai.dev), `--no-install`. The app has a chat (`<AgentChat>`), its route
+(`createAgentHandler`, which keeps your key on the server), a tool drawn with its own component, and a
+demo sign-in to replace with yours.

package/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * npm create @camelai/run-app [directory] [--api-key <key>] [--base-url <url>] [--no-install]
+ *
+ * Copies the Next.js starter into `directory` (default: agent-app), writes .env.local with the API key
+ * (from --api-key or CAMELAI_API_KEY) and installs its dependencies with the package manager it was run with.
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const { version } = JSON.parse(readFileSync(join(here, "package.json"), "utf8"));
+
+function parse(argv) {
+  const options = { directory: undefined, apiKey: process.env.CAMELAI_API_KEY, baseUrl: process.env.CAMELAI_BASE_URL, install: true, help: false };
+  for (let at = 0; at < argv.length; at++) {
+    const arg = argv[at];
+    const value = () => { const next = argv[++at]; if (next === undefined) fail(`${arg} needs a value`); return next; };
+    if (arg === "--api-key") options.apiKey = value();
+    else if (arg.startsWith("--api-key=")) options.apiKey = arg.slice(10);
+    else if (arg === "--base-url") options.baseUrl = value();
+    else if (arg.startsWith("--base-url=")) options.baseUrl = arg.slice(11);
+    else if (arg === "--no-install") options.install = false;
+    else if (arg === "-h" || arg === "--help") options.help = true;
+    else if (arg.startsWith("-")) fail(`Unknown option ${arg}`);
+    else if (options.directory === undefined) options.directory = arg;
+    else fail(`Unexpected argument ${arg}`);
+  }
+  return options;
+}
+function fail(message) { console.error(`create-run-app: ${message}`); process.exit(1); }
+
+const options = parse(process.argv.slice(2));
+if (options.help) {
+  console.log("Usage: npm create @camelai/run-app [directory] [--api-key <key>] [--base-url <url>] [--no-install]");
+  process.exit(0);
+}
+const target = resolve(options.directory ?? "agent-app");
+if (existsSync(target) && readdirSync(target).length) fail(`${target} is not empty`);
+const name = basename(target).toLowerCase().replace(/[^a-z0-9-_.]/g, "-").replace(/^[-_.]+/, "") || "agent-app";
+
+cpSync(join(here, "template"), target, { recursive: true });
+renameSync(join(target, "_gitignore"), join(target, ".gitignore"));
+const manifest = join(target, "package.json");
+writeFileSync(manifest, readFileSync(manifest, "utf8").replaceAll("{{version}}", version).replace('"name": "agent-app"', `"name": "${name}"`));
+const env = [`CAMELAI_API_KEY=${options.apiKey ?? ""}`, ...(options.baseUrl ? [`CAMELAI_BASE_URL=${options.baseUrl}`] : [])].join("\n");
+writeFileSync(join(target, ".env.local"), `${env}\n`, { mode: 0o600 });
+
+const agent = process.env.npm_config_user_agent ?? "";
+const manager = agent.startsWith("pnpm") ? "pnpm" : agent.startsWith("yarn") ? "yarn" : agent.startsWith("bun") ? "bun" : "npm";
+if (options.install) {
+  console.log(`Installing dependencies with ${manager}…`);
+  const result = spawnSync(manager, ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+  if (result.status !== 0) console.warn(`${manager} install failed; run it yourself in ${target}`);
+}
+const relative = options.directory ?? "agent-app";
+console.log(`
+Created ${relative}.
+
+  cd ${relative}${options.install ? "" : `\n  ${manager} install`}${options.apiKey ? "" : "\n  # add your API key to .env.local (https://agents.camelai.dev/console)"}
+  ${manager === "npm" ? "npm run" : manager} dev
+
+Then open http://localhost:3000.`);

package/package.json

@@ -1 +1,29 @@
-{ "name": "@camelai/create-run-app", "version": "0.0.0", "description": "Placeholder: the first release (0.11.0) comes from github.com/qaml-ai/run.", "license": "MIT", "publishConfig": { "access": "public" } }
+{
+  "name": "@camelai/create-run-app",
+  "version": "0.11.0",
+  "description": "Create a Next.js app with a streaming chat to an agent on camelRun: npm create @camelai/run-app",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qaml-ai/run.git",
+    "directory": "packages/create-run-app"
+  },
+  "homepage": "https://agents.camelai.dev",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "create-run-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/.env.example

@@ -0,0 +1,8 @@
+# Your API key from https://agents.camelai.dev/console (keep it server-side: never NEXT_PUBLIC_).
+CAMELAI_API_KEY=
+# The agent's model, if not the one in app/api/agent/route.ts (any of GET /v1/models?available=true).
+# AGENT_MODEL=openrouter/anthropic/claude-sonnet-5.5
+# Only to use a runtime other than https://agents.camelai.dev (e.g. one you run locally).
+# CAMELAI_BASE_URL=http://127.0.0.1:8790
+# Allow anonymous demo users in production (only for a throwaway demo: see the README).
+# DEMO_AUTH=1

package/template/README.md

@@ -0,0 +1,30 @@
+# Agent app
+
+> **⚠ Add your own sign-in before you deploy.** This starter's sign-in is a demo: every browser gets
+> an anonymous user id, so anyone who can reach the app can use your agents (and your API key's
+> credit). In production (`next build && next start`, or any host) the route refuses everyone until
+> you replace `authorize` in `app/api/agent/route.ts` (and `proxy.ts`) with your auth, or opt in to
+> anonymous demo users with `DEMO_AUTH=1`.
+
+A Next.js app with a streaming chat to an agent on [camelRun](https://agents.camelai.dev).
+
+```sh
+cp .env.example .env.local   # add your CAMELAI_API_KEY
+npm install
+npm run dev                  # http://localhost:3000
+```
+
+The agent uses `openrouter/anthropic/claude-sonnet-5.5` (set in `route.ts`, or with `AGENT_MODEL`).
+Your account needs access to it: prepaid credit, or your own OpenRouter key in the console's
+**Models & keys**. `GET /v1/models?available=true` lists the models your key can use.
+
+- `app/api/agent/route.ts`: the route the chat talks to (`createAgentHandler`). It keeps your API key on
+  the server, makes each user their own agent, and defines its instructions and tools. Replace the demo
+  sign-in in `authorize` (and `proxy.ts`) with yours.
+- `app/components/chat.tsx`: the chat (`<AgentChat>`), with `get_weather` drawn by your own component.
+  Theme it with CSS variables (`--agent-accent`, `--agent-radius`, …), or build your own UI with the hooks
+  in `@camelai/run-react` (`useMessages`, `useSend`, `useAgentStatus`, `useInputs`).
+
+Tools in `route.ts` run inside this server, so they need a long-running process (`next dev`,
+`next start`, a container). On serverless hosting, serve them with `serveTools` (with your `tenant`) from
+`@camelai/run/server` and name them in a definition (`agent: { definition: "def_…" }`).

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+.next
+out
+.env*.local
+.env
+next-env.d.ts
+*.tsbuildinfo

package/template/app/api/agent/route.ts

@@ -0,0 +1,39 @@
+import { cookies } from "next/headers";
+import { createAgentHandler } from "@camelai/run/server";
+import { schema, tool } from "@camelai/run";
+
+/**
+ * The route the chat talks to. Your API key (CAMELAI_API_KEY) stays on this server: browsers get
+ * short-lived read-only tokens for their own agent, and everything they send goes through here, as
+ * the user `authorize` returns.
+ */
+export const POST = createAgentHandler({
+  authorize: async () => {
+    // ⚠ A DEMO SIGN-IN: anyone with a browser is a user. Replace this with your own (Clerk, Auth.js,
+    // your session) and return { userId, name } for a signed-in user, or null.
+    // Deployed (production), it refuses everyone unless you opt in with DEMO_AUTH=1.
+    if (process.env.NODE_ENV === "production" && process.env.DEMO_AUTH !== "1") {
+      throw Response.json({ error: { code: "unauthorized", message: "This app has no sign-in yet: add your own in app/api/agent/route.ts (or set DEMO_AUTH=1 to allow anonymous demo users)." } }, { status: 401 });
+    }
+    const userId = (await cookies()).get("demo_user")?.value;
+    return userId && /^[0-9a-f-]{36}$/.test(userId) ? { userId } : null;
+  },
+  agent: {
+    // Any model in GET /v1/models your account can use (?available=true): prepaid credit, or your own key for its provider.
+    model: process.env.AGENT_MODEL ?? "openrouter/anthropic/claude-sonnet-5.5",
+    instructions: "You are a friendly assistant in a demo app. Keep answers short. Use get_weather when asked about the weather.",
+    // Tools run here, in this server, while `next dev` or `next start` runs. For serverless hosting,
+    // serve them with serveTools and a definition instead (see the README).
+    tools: {
+      get_weather: tool({
+        description: "The current weather in a city",
+        input: schema.Object({ city: schema.String({ maxLength: 100 }) }),
+        execute: async ({ city }) => {
+          // Swap in a real weather API. This one is made up, so the demo needs no other key.
+          const seed = [...city].reduce((sum, char) => sum + char.charCodeAt(0), 0);
+          return { city, temperatureC: 8 + (seed % 22), conditions: ["Sunny", "Cloudy", "Rain", "Windy"][seed % 4] };
+        },
+      }),
+    },
+  },
+});

package/template/app/components/chat.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { AgentChat } from "@camelai/run-react/ui";
+import type { ToolRenderProps } from "@camelai/run-react";
+
+/** A tool call rendered with your own component ("generative UI"): here, get_weather as a card. */
+function WeatherCard({ args, state, result }: ToolRenderProps) {
+  const data = result?.data as { city: string; temperatureC: number; conditions: string } | undefined;
+  return (
+    <div style={{ border: "1px solid var(--agent-border)", borderRadius: 12, padding: "12px 16px", maxWidth: 280 }}>
+      <div style={{ fontSize: 13, color: "var(--agent-muted-fg)" }}>Weather · {String(args.city ?? "…")}</div>
+      {data ? (
+        <div style={{ fontSize: 28, fontWeight: 600 }}>{data.temperatureC}°C <span style={{ fontSize: 15, fontWeight: 400 }}>{data.conditions}</span></div>
+      ) : (
+        <div style={{ color: "var(--agent-muted-fg)" }}>{state === "error" ? "Could not get the weather." : "Checking…"}</div>
+      )}
+    </div>
+  );
+}
+
+export function Chat() {
+  return (
+    <AgentChat
+      endpoint="/api/agent"
+      tools={{ get_weather: WeatherCard }}
+      suggestions={["What's the weather in Lisbon?", "Write a haiku about deploys", "Explain SSE in two sentences"]}
+      style={{ flex: 1, minHeight: 0 }}
+    />
+  );
+}

package/template/app/globals.css

@@ -0,0 +1,5 @@
+html, body { height: 100%; margin: 0; }
+body { background: var(--page-bg, #fff); }
+@media (prefers-color-scheme: dark) { body { --page-bg: #0a0a0a; } }
+main { height: 100dvh; display: flex; flex-direction: column; }
+header { padding: 12px 16px; font: 600 15px/1.4 ui-sans-serif, system-ui, sans-serif; color: #71717a; }

package/template/app/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#18181b"/><path d="M9 11h14v8H14l-5 4z" fill="#fafafa"/></svg>

package/template/app/layout.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import "@camelai/run-react/styles.css";
+import "./globals.css";
+
+export const metadata = { title: "Agent app", description: "A chat with an agent on camelRun" };
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,10 @@
+import { Chat } from "./components/chat";
+
+export default function Page() {
+  return (
+    <main>
+      <header>Agent app</header>
+      <Chat />
+    </main>
+  );
+}

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "agent-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@camelai/run": "^{{version}}",
+    "@camelai/run-react": "^{{version}}",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^5"
+  }
+}

package/template/proxy.ts

@@ -0,0 +1,17 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+/**
+ * A stand-in for your sign-in: each browser gets a random, http-only user id, so every visitor has
+ * their own agent. Replace it with your auth (Clerk, Auth.js, your session) and read that in
+ * app/api/agent/route.ts instead.
+ */
+export function proxy(request: NextRequest) {
+  // Deployed, there are no demo users unless you opt in (DEMO_AUTH=1): see app/api/agent/route.ts.
+  if (process.env.NODE_ENV === "production" && process.env.DEMO_AUTH !== "1") return NextResponse.next();
+  if (request.cookies.get("demo_user")) return NextResponse.next();
+  const response = NextResponse.next();
+  response.cookies.set("demo_user", crypto.randomUUID(), { httpOnly: true, sameSite: "lax", secure: request.nextUrl.protocol === "https:", path: "/", maxAge: 60 * 60 * 24 * 365 });
+  return response;
+}
+
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };

package/template/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}