Skip to main content

​
arkor build and arkor start

arkor build and arkor start are the headless equivalent of Studio’s Run training button. Use them when you want to run a trainer without booting the UI: in CI, on a server, or from another script. Studio’s Run training internally spawns arkor start (without an entry argument), so the runtime path is the same in both flows.

​
arkor build

Bundles src/arkor/index.ts into .arkor/build/index.mjs using esbuild.

​
Synopsis

arkor build [entry]

pnpm build

​
Argument

ArgumentDefaultDescription
entrysrc/arkor/index.tsSource entry to bundle. Both relative and absolute paths work.

​
Output

.arkor/build/index.mjs (outDir defaults to .arkor/build). The output is a single ESM file targeting Node 22.22, with packages: "external" so bare specifiers (arkor, anything from node_modules) stay external and the artifact resolves the runtime SDK from your installed node_modules. Only relative imports are bundled inline. If the entry does not exist, arkor build throws with a hint to either create src/arkor/index.ts or pass an explicit entry.

​
arkor start

Runs .arkor/build/index.mjs. The runner imports the bundle, finds the registered trainer (preferring export const arkor, then export const trainer, then the default export), and calls trainer.start() followed by trainer.wait().

​
Synopsis

arkor start [entry]

pnpm start

​
Argument

ArgumentDefaultDescription
entrynoneWhen provided, arkor start rebuilds the project with this entry before running. When omitted, an existing build artifact is reused; if it does not exist, arkor start auto-builds with the default entry first.
The auto-build-on-missing behavior exists so Studio’s “Run training” does not have to chain two spawns. From a script you usually want to call arkor build and arkor start explicitly so a build failure surfaces before you commit to running.

​
Behavior

SituationWhat arkor start does
entry argument passedRebuild with the given entry, then run.
Artifact missing, no entryAuto-build with the default entry, then run.
Artifact present, no entryReuse the artifact, run as-is.
The “reuse the artifact” path is what lets Studio surface trainer edits via its /api/manifest rebuild rather than the train endpoint. For a CLI-only workflow, run arkor build whenever you change src/arkor/.

​
Errors

arkor build:
MessageWhat it meansFix
Build entry not found: <abs-path>. Create src/arkor/index.ts or pass an explicit entry argument.The default entry does not exist and no explicit entry was passed.Run from a project root (the directory containing src/arkor/index.ts), or pass an entry: arkor build path/to/entry.ts.
arkor start:
MessageWhat it meansFix
Build entry not found: <abs-path>. Create src/arkor/index.ts or pass an explicit entry argument.arkor start runs arkor build first whenever you pass an entry argument, or whenever .arkor/build/index.mjs is missing. A bad entry path surfaces here, not at the runner stage.Pass an entry that exists, or omit it and rely on the default src/arkor/index.ts.
Training entry must export 'arkor' (from createArkor({...})) or 'trainer' (from createTrainer({...})), or default-export one of them.The bundle imported successfully but did not expose any of the supported export shapes.See Project structure § src/arkor/ for the three accepted forms (named arkor, named trainer, or default).
runTrainer (programmatic):
MessageWhat it meansFix
Training entry not found: <abs-path>. Provide a path or create src/arkor/index.ts.Surfaces when the runner is invoked directly (e.g. import { runTrainer } from "arkor") with a path that does not exist. The CLI does not hit this path; arkor start would have failed earlier in the build stage.Pass a path that exists, or import "./src/arkor/index.ts" first to catch it at module-load time.

​
Examples

Build then start, two steps: 
pnpm build
pnpm start
One step, force a rebuild from a different entry: 
pnpm start src/arkor/experiment.ts
Rebuild stale artifact between trainer edits: 
# After editing src/arkor/trainer.ts:
pnpm build && pnpm start

​
See also