Quick start

npx create-octoflow-app my-agent
cd my-agent
npm install
npx tsx agent.ts

You need one LLM backend ready: set ANTHROPIC_API_KEY (or OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY), or run a local Ollama.

What you get

A tiny, heavily commented standalone TypeScript project built on octoflow-core:

my-agent/
├── agent.ts          ← the agent — discover backend → send → print (commented)
├── agent.test.ts     ← a vitest unit test (no network)
├── package.json      ← octoflow-core pinned to a real version; lean scripts
├── tsconfig.json
├── vitest.config.ts
├── .gitignore
└── README.md

The stack is the lean "fast combo" for a Node agent app — no bundler:

| Concern | Tool | |---------|------| | Run | tsx (npm run dev) | | Type-check | tsc --noEmit (npm run typecheck) | | Test | vitest (npm test) | | Format | prettier (npm run format) |

Why no Vite/esbuild? Vite is a frontend bundler and a poor fit for a Node/CLI agent; an agent app doesn't need bundling at all. Add a bundler only if you later ship a built artifact.

Usage

npx create-octoflow-app [directory] [--force] [--core-version=<version>] [--sandbox] [--integrate=<target>]

• directory — where to scaffold (default my-octoflow-agent).
• --force — scaffold into a non-empty directory (with --integrate, overwrite existing wiring files).
• --core-version — pin a specific octoflow-core version instead of resolving the latest.
• --sandbox — generate an agent whose tool/code execution runs in a hardened Docker container (createDockerEnvironment: all capabilities dropped, no network, capped memory). Adds the dockerode dependency; needs a running Docker daemon.
• --integrate=<target> — add OctoFlow's wiring to an existing React app instead of scaffolding a new one. Targets: next, electron, react-native (see below).

Non-interactive by design, so it works cleanly from scripts and agents.

Adding OctoFlow to an existing app — --integrate

The agent is a server-tier component: it holds your LLM key and must never ship to a browser or mobile bundle. So rather than fork-and-maintain a template per UI framework, create-octoflow-app delegates the app skeleton to that framework's own create-* tool and adds only the OctoFlow wiring — the astro add model.

Every target uses the same two layers: octoflow-react (OctoFlowProvider + useOctoFlowChat) on the client, and OctoFlow's AG-UI gateway (octoflow-core) on the server.

| Target | Skeleton (delegate to) | Where the agent runs | Adds | |--------|------------------------|----------------------|------| | next (fullstack) | create-next-app | Route handler (app/api/octoflow/agui/run) | octoflow-core + octoflow-react | | electron (desktop) | @quick-start/electron | Main process (gateway on loopback, IPC to renderer) | octoflow-core + octoflow-react | | react-native (mobile) | create-expo-app | A remote backend the app calls (e.g. the next target) | octoflow-react only |

npx create-next-app@latest my-app        # delegate the skeleton to the official tool
cd my-app
npx create-octoflow-app . --integrate=next

Each target writes its wiring files (server tier + an octoflow-react client screen), a .env.example, and an OCTOFLOW.md with the exact setup steps, then merges the right deps into your package.json.

Two caveats are documented in the generated OCTOFLOW.md:

• Electron — the renderer and the loopback gateway are different origins, so you must add a CORS step (or proxy over IPC). The octoflow-* wiring is type-checked; that last hop is yours to enable.
• React Native — AG-UI streaming needs a fetch with a readable body, which RN lacks by default; install a streaming-fetch polyfill (commands in OCTOFLOW.md).

How it pins octoflow-core

It resolves the latest published octoflow-core at scaffold time and writes it as a caret range (e.g. ^1.1.0) — you get "latest" without the non-reproducible builds and supply-chain risk of a literal "latest" dependency.

Relationship to octoflow-agent-factory-cli

Two complementary front doors:

• create-octoflow-app (this) — deterministic, zero-LLM: an instant, reproducible starter repo.
• octoflow-agent-factory-cli — LLM-driven: describe an agent in English and it generates + runs it.

Next steps after scaffolding

Add tools, memory, RAG, or multi-agent topologies — see the OctoFlow docs and the feature catalog.