Quickstart

Scaffold an Arkor project, fine-tune a small open-weight LLM, and chat with it from a local Studio.

In a few minutes you will go from zero to a fine-tuned model you can chat with in a local Playground. The training itself takes 7 to 12 minutes; setup time depends on your connection and what is already installed.

Prerequisites

• Node.js 22.22.0 or newer. Node 24 is recommended.
• A package manager. pnpm, npm, yarn, and bun all work. Each snippet below ships as a tab group, so pick the one you use and the rest of the page follows.
• A working internet connection. Training runs on Arkor’s managed GPUs.

No account, no credit card, no GPU on your machine.

1. Scaffold a project

pnpm

pnpm create arkor my-arkor-app
cd my-arkor-app

The scaffolder asks which template you want. Pick the one closest to what you eventually want to build:

Template	Task	Output shape	Estimated training
triage	Support triage	{ category, urgency, summary, nextAction }	~7 min
translate	9-language translation	{ translation, detectedLanguage }	~7 min
redaction	PII redaction	{ redactedText, redactedCount, tags }	~12 min

Each template pairs the same small open-weight base (gemma-4-E4B-it) with a curated public dataset on HuggingFace. The training is real and finishes in minutes, so you get to see the whole loop end to end.

To skip the prompt:

pnpm

pnpm create arkor my-arkor-app --template triage

Running under Claude Code (CLAUDECODE=1)

Claude Code spawns child processes with CLAUDECODE=1, and it cannot answer interactive prompts. To prevent the agent from silently scaffolding with hidden defaults, create-arkor flips into a strict mode under this env var: a curated set of flags becomes required (see the list below), and a missing one produces a stderr message listing the suggested re-invocation rather than running. The same rule applies to arkor init, with one extra requirement here: [dir] (or --name) is also mandatory, since create-arkor’s default fallback for a missing positional is the generic arkor-project/ subdirectory, almost always an oversight rather than an intentional choice. Inputs that contain no ASCII letter or digit (empty, whitespace-only, or punctuation-only like !!!) are rejected as well, because sanitise() would collapse them back to that same generic fallback. Deliberate names whose final slug happens to be arkor-project (for example Arkor Project, arkor_project, Arkor.Project, or anything else where a separator gets rewritten to -) are accepted: the alphanumeric content shows the agent typed a real name.

Required flags (or pass -y/--yes to opt back into “accept all defaults”):

• [dir] (e.g. my-arkor-app) or --name <name>: explicit project name. Values with no ASCII letter or digit (empty, whitespace-only, or punctuation-only like !!!) are rejected because they would collapse to the generic arkor-project fallback; deliberate inputs that happen to sanitise to arkor-project (Arkor Project, arkor_project, …) are accepted.
• --template <triage|translate|redaction>
• --git (recommended; matches the interactive default) or --skip-git
• A package-manager flag: --use-npm / --use-pnpm / --use-yarn / --use-bun, or --skip-install
• --agents-md (recommended, especially under CLAUDECODE) or --no-agents-md

Sample stderr when a flag is missing:

create-arkor: CLAUDECODE=1 detected. Interactive prompts are disabled.
Re-run with explicit flags:
  [dir] (e.g. `my-arkor-app`) or --name <name>
      Project directory (positional) and the `package.json` name. Without `--name`, the basename of `[dir]` is used. Inputs with no ASCII letter or digit (empty, whitespace-only, or punctuation-only like `!!!` / `***`) are rejected because they would collapse to the generic `arkor-project` fallback inside `sanitise()`.
  --template <triage|translate|redaction>
      Starter template: `triage` (support routing), `translate` (9-language translation), or `redaction` (PII removal).
  --git (recommended) or --skip-git
      `--git` runs `git init` and creates an initial commit (matches the interactive default); `--skip-git` leaves git setup to the user.
  --use-pnpm (or --use-npm / --use-yarn / --use-bun, or --skip-install)
      Which package manager to run `install` with after scaffolding. `--skip-install` leaves the install step to the user.
  --agents-md (recommended) or --no-agents-md
      `--agents-md` writes `AGENTS.md` + `CLAUDE.md` to brief AI coding agents that arkor post-dates their training data (recommended, especially under CLAUDECODE); `--no-agents-md` skips them.
Or pass -y/--yes to accept all defaults.

The exit code is 1 and no scaffold work happens before the early exit, so the parent directory stays pristine.

2. Look at what was generated

my-arkor-app/
├── src/arkor/
│   ├── index.ts        # createArkor({ trainer })
│   └── trainer.ts      # createTrainer({ ... })
├── arkor.config.ts
├── .arkor/             # state + build artifacts (gitignored)
└── package.json        # dev / build / start

The two files that matter for now:

• src/arkor/trainer.ts holds your trainer definition. Model, dataset, LoRA settings, hyperparameters, and lifecycle callbacks all live here.
• src/arkor/index.ts is the entry point. It calls createArkor({ trainer }) so the CLI and Studio can discover what to run.

Open trainer.ts. The shape is the same across templates; only the dataset, output schema, and example prompts differ.

3. Open Studio and start a run

pnpm

pnpm dev

This runs arkor dev, which boots Studio at http://localhost:4000. Studio is the UI; arkor dev itself does not start training and does not watch your trainer files.

In the browser, click Run training. Studio submits the job to the managed backend in the background and streams the output back into the page. The first time you trigger anything, an anonymous workspace is created automatically: no signup, no credit card.

Once a run is in flight, three views matter:

• Jobs. A list of training runs. Click into one to see live status.
• Loss chart and event log. As the run streams from the managed GPU, the loss curve updates and the log tail shows training events. The first run takes 7 to 12 minutes depending on the template.
• Playground. After a job completes, pick the final adapter from the selector and chat with it. Use the mode toggle to switch between the base model and the adapter. To run inference on intermediate checkpoints while a run is still in flight, use onCheckpoint callbacks instead of Studio.

If you edit src/arkor/ between runs, refresh the Run training page (or run arkor build) before the next click so the new code is what runs.

4. Tie runs to an account (optional)

Anonymous workspaces are useful for trying things out, but the work is tied to the anonymous token on this local machine and is not visible from another device or another account. To keep training under an account, sign in with OAuth before you start the next run:

pnpm

pnpm arkor login --oauth

This runs the Arkor Cloud OAuth (PKCE) flow on a loopback port and links your local credentials to an account. From then on, runs from this machine show up under that account on any device.

The scaffolded project installs arkor as a local devDependency, so use your package manager’s local-bin runner over a bare arkor invocation unless you have installed the CLI globally. The generated project README walks through the equivalent setup for pnpm, npm, yarn, and bun.

A few caveats. Running arkor login without a flag opens an interactive picker that defaults to Anonymous; accepting the default mints a brand-new anonymous token (a new anonymousId) and overwrites ~/.arkor/credentials.json, so it lands you in a different workspace from the previous anonymous session, not a refresh of it. Switching to OAuth overwrites the same file and does not migrate prior anonymous workspaces or jobs into the account. Merging anonymous work into an OAuth account once you sign in is on the roadmap; until that lands, sign in before the runs you want associated with the account.

5. Where to go next

• Concepts. Read Concepts to build a mental model of createArkor, createTrainer, the lifecycle callbacks, and Studio.
• Customize the trainer. Open src/arkor/trainer.ts and tweak lora.r, maxSteps, or add more callbacks. Refresh the Run training page (or run arkor build) before the next click so your edits land.
• Try another template. Re-run the scaffolder with a different --template to compare.