For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/guide/start/installation.md.
Skip to main content
agent-bundle
  • English

      • Installation

      Requirements

      • Node.js 22.19 or later to run the compiler and the developer Workbench.
      • A package manager: npm, pnpm, yarn, and bun all work; the examples below use npm.

      Generated executables target Node.js 22.12 or newer by default. runtime: { node: '24.0' } raises that floor (it can never be lowered), and the selected floor is recorded as runtime.node in the artifact manifest.

      Install from the preview channel

      Packages are distributed through pkg.pr.new, not the npm registry. Install the preview tarballs CI publishes for every pull request and for the tip of main:

      npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha-or-pr>

      Use a PR number or the SHA of a commit whose package-preview run succeeded, a main commit overtaken before its run finished has none. Short SHAs work, and a SHA is the right form for lockfiles and reproducible setups; a PR number tracks that pull request's most recent build.

      Pair the runtime package from the same commit

      Projects with route modules also need @agent-bundle/runtime, published to the same channel:

      npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@5685521
npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@5685521

      Install both from one SHA or PR number. agent-bundle declares @agent-bundle/runtime as an optional peer (the runtime package declares no agent-bundle peer), and the publish (--peerDeps) rewrites that peer range inside the agent-bundle preview tarball to the exact preview version of the runtime built from the same commit, so a matched pair installs with stock npm. Mixing two different SHAs fails with ERESOLVE by design, the range to inspect is the one in the installed agent-bundle package.

      A preview scaffolder derives its compiler/runtime pair from the shared commit SHA. For a runtime template, an explicit --framework-version must therefore be an exact pkg.pr.new compiler URL or the local agent-bundle.tgz beside agent-bundle-runtime.tgz.

      pnpm and yarn accept the same URLs (pnpm add <url>, yarn add agent-bundle@<url>).

      Preview versions are spelled 0.0.0-preview-<sha>. They are built from the same output the release gates verify, but they are not npm releases. See Preview packages for pinning details and where previews come from.

      Optional dependencies

      These are installed only when a project uses the surface that needs them:

      PackageNeeded for
      @agent-bundle/runtimeRoute modules, rendered Skills, and rendered CLI commands or scripts. Generated entries import it the same way your code does.
      @rstest/coreRunning the framework test harness. It is an optional peer dependency, so a project that never tests routes never installs it.
      reactRendering route modules and asserting on them. Also an optional peer dependency.
      typescriptlib.dts declaration generation, which resolves typescript from the project.

      agent-bundle and @agent-bundle/runtime accept the same React ^19.2.0 line. The runtime declares that range for both React and React DOM, so a clean npm install can select one matching pair without preinstalling React or bypassing peer checks. Routed scaffolds still pin one known-good React/React DOM pair intentionally: generated projects start reproducibly, and their committed lockfiles preserve that pair.

      @agent-bundle/runtime declares zod as a ^4.6.4 peer rather than a dependency for the same reason: route and state definitions hand Zod schemas across the runtime's API, and Zod 4 brands schema types by minor version. A nested zod@4.5.x therefore rejects a consumer schema from zod@4.6.x (Type '6' is not assignable to type '5'). Two installations of the same minor still typecheck; the peer is so the project and the runtime resolve one copy and stay on compatible minors. Existing projects still pinned to zod@4.5.x, or any version below 4.6.4, must upgrade that direct dependency before installing this runtime, npm otherwise rejects the required peer with ERESOLVE.

      Pin a Version Packages commit

      A Version Packages merge bumps repository versions and publishes the resulting commit through pkg.pr.new. Consumers still pin the merge SHA:

      npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha>
npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha> my-plugin

      Use the same SHA for @agent-bundle/runtime. The preview scaffolder derives that same-SHA compiler and runtime pair automatically. No npm registry credential is needed.

      Verify the install

      npx agent-bundle --help
npx agent-bundle validate --root .

      validate checks project source. Once you have built something, validate --artifact artifact checks the built plugin root instead, the one directory every selected host installs, with no project sources required.

      Next: Quick start.