AgentlyHQ · fuxingloh · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026
diff --git a/bun.lock b/bun.lock
diff --git a/examples/next-with-aixyz/.gitignore b/examples/next-with-aixyz/.gitignore
@@ -0,0 +1,18 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+/.pnp
+.pnp.js
+.yarn*
+pnpm-lock.yaml
+
+# next
+.next
+
+# aixyz
+.aixyz
+
+# env files (can opt-in for committing if needed)
+#.env
+.env.local
diff --git a/examples/next-with-aixyz/README.md b/examples/next-with-aixyz/README.md
@@ -0,0 +1 @@
+# Template: Next.js with aixyz.sh
diff --git a/examples/next-with-aixyz/aixyz.config.ts b/examples/next-with-aixyz/aixyz.config.ts
@@ -0,0 +1,13 @@
+import type { AixyzConfig } from "aixyz/config";
+
+const config: AixyzConfig = {
+  name: "Next.js with aixyz",
+  description: "Demonstrates running an aixyz agent alongside a Next.js application using @aixyz/next.",
+  version: "1.0.0",
+  x402: {
+    payTo: "0x0799872E07EA7a63c79357694504FE66EDfE4a0A",
+    network: "eip155:8453",
+  },
+};
+
+export default config;
diff --git a/examples/next-with-aixyz/aixyz/agent.ts b/examples/next-with-aixyz/aixyz/agent.ts
@@ -0,0 +1,12 @@
+import { fake } from "aixyz/model";
+import { ToolLoopAgent } from "ai";
+
+export const accepts = {
+  scheme: "free",
+};
+
+export default new ToolLoopAgent({
+  model: fake((message) => {
+    return message;
+  }),
+});
diff --git a/examples/next-with-aixyz/aixyz/erc-8004.ts b/examples/next-with-aixyz/aixyz/erc-8004.ts
@@ -0,0 +1,17 @@
+import type { ERC8004Registration } from "aixyz/erc-8004";
+
+const metadata: ERC8004Registration = {
+  /**
+   * `aixyz erc-8004 register` will write to this field.
+   */
+  registrations: [],
+  supportedTrust: ["reputation"],
+};
+
+/**
+ * Declaring `export default registration`, two endpoints will be available:
+ *
+ * GET /_aixyz/erc-8004.json
+ * GET /.well-known/erc-8004.json
+ */
+export default metadata;
diff --git a/examples/next-with-aixyz/aixyz/tools/hammer.ts b/examples/next-with-aixyz/aixyz/tools/hammer.ts
@@ -0,0 +1,16 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+export const accepts = {
+  scheme: "free",
+};
+
+export default tool({
+  description: "Hammer a nail into something.",
+  inputSchema: z.object({
+    nail: z.string(),
+  }),
+  execute: async ({ nail }) => {
+    return "hamming " + nail;
+  },
+});
diff --git a/examples/next-with-aixyz/app/page.tsx b/examples/next-with-aixyz/app/page.tsx
@@ -0,0 +1,9 @@
+export default function Home() {
+  return (
+    <html>
+      <body>
+        <h1>Next.js with aixyz.sh</h1>
+      </body>
+    </html>
+  );
+}
diff --git a/examples/next-with-aixyz/next.config.ts b/examples/next-with-aixyz/next.config.ts
@@ -0,0 +1,6 @@
+import type { NextConfig } from "next";
+import { experimental_withAixyz } from "@aixyz/next";
+
+const nextConfig: NextConfig = {};
+
+export default experimental_withAixyz(nextConfig);
diff --git a/examples/next-with-aixyz/package.json b/examples/next-with-aixyz/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "next-with-aixyz",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "bun --bun next build",
+    "dev": "bun --bun next dev"
+  },
+  "dependencies": {
+    "@aixyz/next": "^0",
+    "ai": "^6",
+    "aixyz": "^0",
+    "next": "16.1.6",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/bun": "^1",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^5"
+  }
+}
diff --git a/examples/next-with-aixyz/tsconfig.json b/examples/next-with-aixyz/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "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", "**/*.mts"],
+  "exclude": ["node_modules"]
+}
diff --git a/examples/next-with-aixyz/vercel.json b/examples/next-with-aixyz/vercel.json
@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "buildCommand": "bunx aixyz build"
+}
diff --git a/packages/aixyz-cli/build/AixyzServerPlugin.ts b/packages/aixyz-cli/build/AixyzServerPlugin.ts
@@ -38,8 +38,8 @@ if (import.meta.main) {
   };
 }
 
-export function getEntrypointMayGenerate(cwd: string, mode: "dev" | "build"): string {
-  const appDir = resolve(cwd, "app");
+export function getEntrypointMayGenerate(cwd: string, appDirName: string, mode: "dev" | "build"): string {
+  const appDir = resolve(cwd, appDirName);
 
   if (existsSync(resolve(appDir, "server.ts"))) {
     return resolve(appDir, "server.ts");

diff --git a/packages/aixyz-cli/build/index.ts b/packages/aixyz-cli/build/index.ts
@@ -8,10 +8,6 @@ import { getAixyzConfig } from "@aixyz/config";
 import { loadEnvConfig } from "@next/env";
 import chalk from "chalk";
 
-interface BuildOptions {
-  output?: string;
-}
-
 export const buildCommand = new Command("build")
   .description("Build the aixyz agent")
   .option("--output <type>", "Output format: 'standalone', 'vercel', or 'executable'")
@@ -51,16 +47,23 @@ Examples:
   )
   .action(action);
 
-async function action(options: BuildOptions = {}): Promise<void> {
+type BuildOptions = {
+  output?: string;
+  // Internal option, not exposed to CLI
+  appDir?: string;
+};
+
+export async function action(options: BuildOptions = {}): Promise<void> {
   const cwd = process.cwd();
   loadEnvConfig(cwd, false);
   process.env.NODE_ENV = "production";
   process.env.AIXYZ_ENV = "production";
-  const entrypoint = getEntrypointMayGenerate(cwd, "build");
 
   // Determine output target: explicit CLI flag takes precedence, then config file, then auto-detect VERCEL env
   const config = getAixyzConfig();
   const target = options.output ?? config.build?.output ?? (process.env.VERCEL === "1" ? "vercel" : "standalone");
+  const appDir = options.appDir || "app";
+  const entrypoint = getEntrypointMayGenerate(cwd, appDir, "build");
 
   if (target === "vercel") {
     console.log(chalk.cyan("▶") + " Building for " + chalk.bold("Vercel") + "...");

diff --git a/packages/aixyz-cli/dev/index.ts b/packages/aixyz-cli/dev/index.ts
@@ -3,14 +3,21 @@ import { existsSync, watch } from "fs";
 import { loadEnvConfig } from "@next/env";
 import { Command } from "commander";
 import { getEntrypointMayGenerate } from "../build/AixyzServerPlugin";
+import chalk from "chalk";
 import pkg from "../package.json";
 
 export const devCommand = new Command("dev")
   .description("Start a local development server")
   .option("-p, --port <port>", "Port to listen on", "3000")
   .action(action);
 
-async function action(options: { port?: string }): Promise<void> {
+type DevOptions = {
+  port?: string;
+  // Internal option, not exposed to CLI
+  appDir?: string;
+};
+
+export async function action(options: DevOptions): Promise<void> {
   const cwd = process.cwd();
 
   // Load environment config
@@ -20,15 +27,15 @@ async function action(options: { port?: string }): Promise<void> {
   const envFileNames = loadedEnvFiles.map((f) => relative(cwd, f.path));
 
   const port = options.port || process.env.PORT || "3000";
+  const appDir = options.appDir || "app";
   const baseUrl = `http://localhost:${port}`;
 
   console.log("");
-  console.log(`⟡ aixyz.sh v${pkg.version}`);
-  console.log("");
-  console.log(`- A2A:          ${baseUrl}/.well-known/agent-card.json`);
-  console.log(`- MCP:          ${baseUrl}/mcp`);
+  console.log(chalk.blueBright(`➫ aixyz.sh v${pkg.version}`));
+  console.log(`- A2A:           ${baseUrl}/.well-known/agent-card.json`);
+  console.log(`- MCP:           ${baseUrl}/mcp`);
   if (envFileNames.length > 0) {
-    console.log(`- Environments: ${envFileNames.join(", ")}`);
+    console.log(`- Environments:  ${envFileNames.join(", ")}`);
   }
   console.log("");
 
@@ -38,7 +45,7 @@ async function action(options: { port?: string }): Promise<void> {
   let restarting = false;
 
   function startServer() {
-    const endpoint = getEntrypointMayGenerate(cwd, "dev");
+    const endpoint = getEntrypointMayGenerate(cwd, appDir, "dev");
     child = Bun.spawn(["bun", workerPath, endpoint, port], {
       cwd,
       stdout: "inherit",
@@ -76,7 +83,7 @@ async function action(options: { port?: string }): Promise<void> {
     }, 100);
   }
 
-  watch(resolve(cwd, "app"), { recursive: true }, (_event, filename) => {
+  watch(resolve(cwd, appDir), { recursive: true }, (_event, filename) => {
     scheduleRestart(filename ? `${filename} changed` : "file changed");
   });
 

diff --git a/packages/aixyz-cli/dev/worker.ts b/packages/aixyz-cli/dev/worker.ts
@@ -1,3 +1,5 @@
+import chalk from "chalk";
+
 async function main() {
   const entrypoint = process.argv[2];
   const port = parseInt(process.argv[3], 10);
@@ -18,7 +20,7 @@ async function main() {
 
   app.express.listen(port, () => {
     const duration = Math.round(performance.now() - startTime);
-    console.log(`Ready in ${duration}ms`);
+    console.log(chalk.blueBright("✓") + ` Ready in ${duration}ms`);
     console.log("");
   });
 }

diff --git a/packages/aixyz-next/index.ts b/packages/aixyz-next/index.ts
@@ -0,0 +1,57 @@
+import type { NextConfig } from "next";
+import { action as devAction } from "@aixyz/cli/dev";
+
+interface WithAixyzOptions {
+  dir?: string;
+}
+
+function getFreePort() {
+  const server = Bun.serve({ port: 0, fetch: () => new Response() });
+  const port = server.port!;
+  void server.stop(true);
+  return port;
+}
+
+export function experimental_withAixyz(nextConfig: NextConfig = {}, options?: WithAixyzOptions): NextConfig {
+  const dir = options?.dir ?? "aixyz";
+
+  if (process.env.NODE_ENV === "development") {
+    const aixyzPort = getFreePort();
+    devAction({ port: String(aixyzPort), appDir: dir });
+
+    return {
+      ...nextConfig,
+      rewrites: async () => {
+        const existing = await nextConfig.rewrites?.();
+
+        const aixyzRewrites = [
+          {
+            source: "/.well-known/erc-8004.json",
+            destination: `http://localhost:${aixyzPort}/.well-known/erc-8004.json`,
+          },
+          { source: "/_aixyz/erc-8004.json", destination: `http://localhost:${aixyzPort}/_aixyz/erc-8004.json` },
+          { source: "/_aixyz/:path*", destination: `http://localhost:${aixyzPort}/:path*` },
+        ];
+
+        if (!existing) {
+          return aixyzRewrites;
+        }
+
+        if (Array.isArray(existing)) {
+          return [...existing, ...aixyzRewrites];
+        }
+
+        return {
+          beforeFiles: existing.beforeFiles ?? [],
+          afterFiles: [...(existing.afterFiles ?? []), ...aixyzRewrites],
+          fallback: existing.fallback ?? [],
+        };
+      },
+    };
+  }
+
+  if (process.env.NODE_ENV === "production") {
+  }
+
+  return nextConfig;
+}
diff --git a/packages/aixyz-next/package.json b/packages/aixyz-next/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@aixyz/next",
+  "version": "0.0.0",
+  "description": "Next.js integration for aixyz",
+  "keywords": [
+    "ai",
+    "payments",
+    "agent",
+    "aixyz",
+    "next"
+  ],
+  "homepage": "https://aixyz.sh",
+  "bugs": "https://github.com/AgentlyHQ/aixyz/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentlyHQ/aixyz.git"
+  },
+  "license": "MIT",
+  "author": "AgentlyHQ",
+  "type": "module",
+  "files": [
+    "**/*.ts"
+  ],
+  "dependencies": {
+    "@aixyz/cli": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "next": "^16"
+  }
+}
diff --git a/packages/aixyz-next/tsconfig.json b/packages/aixyz-next/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}