API reference

The Arkor SDK: createArkor, createTrainer, lifecycle callbacks, infer, and the helpers around them.

The arkor package exposes the TypeScript surface that the CLI and Studio sit on top of. Everything you need for a typical project lives in three primitives plus their typed inputs.

Minimal example

// src/arkor/trainer.ts
import { createTrainer } from "arkor";

export const trainer = createTrainer({
  name: "support-bot-v1",
  model: "unsloth/gemma-4-E4B-it",
  dataset: { type: "huggingface", name: "arkorlab/triage-demo" },
  lora: { r: 16, alpha: 16 },
  maxSteps: 100,
});

// src/arkor/index.ts
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });

That is the whole shape arkor dev and arkor start discover.

Main API

Symbol	Page
`createArkor(input)`	Project manifest. Wraps a `Trainer` so the CLI / Studio can find it.
`createTrainer(input)`	The fine-tuning run definition: model, dataset, LoRA, hyperparameters, callbacks.
`Trainer.start / wait / cancel`	Run-control methods. `wait()` is where lifecycle callbacks fire.
`TrainerCallbacks`	The five lifecycle callbacks (`onStarted`, `onLog`, `onCheckpoint`, `onCompleted`, `onFailed`).
`InferArgs` / `infer`	Inference inside `onCheckpoint`. Returns a raw `Response`.
`DatasetSource`	HuggingFace dataset name or blob URL.

Auxiliary helpers (advanced)

These are exported for code that drives Arkor outside the CLI flow, e.g. running training from your own server or a script. Most projects do not need them.

Symbol	Source	Purpose
`runTrainer(file?)`	`core/runner.ts`	What `arkor start` calls under the hood. Resolves the entry, picks the trainer (preferring `arkor`, then `trainer`, then default export), runs `start()` + `wait()`.
`readCredentials()` / `writeCredentials()` / `ensureCredentials()`	`core/credentials.ts`	Read or write `~/.arkor/credentials.json`. `readCredentials` returns `null` when the file is absent or its content is corrupt (invalid JSON), so a truncated file is treated like a missing one; it rethrows only when the file is present but unreadable (EACCES / EIO / EISDIR), so a valid-but-temporarily-locked login is never silently discarded. `ensureCredentials` returns the existing record if present, and when credentials are absent or corrupt it warns and bootstraps a fresh anonymous identity (calls `requestAnonymousToken` and persists it); it throws when the file is present-but-unreadable or the anonymous-token bootstrap itself fails (network / token-endpoint error). `writeCredentials` writes atomically (temp file + rename). The file is assumed to be SDK-written.
`requestAnonymousToken(baseUrl, kind?)`	`core/credentials.ts`	Mint a fresh anonymous token directly. The CLI uses this on `arkor login --anonymous` and on first `arkor dev`.
`credentialsPath()`	`core/credentials.ts`	Absolute path to `~/.arkor/credentials.json`.
`readState(cwd?)` / `writeState(state, cwd?)` / `statePath(cwd?)`	`core/state.ts`	Read or write `.arkor/state.json` (project routing).
`isArkor(value)`	`core/arkor.ts`	Type guard for the manifest.
`CloudApiClient`	`core/client.ts`	Typed client for the cloud API. Exposes `listDeployments` / `createDeployment` / `createDeploymentKey` etc. for managing `*.arkor.app` inference URLs. See Deployments for the full method list and examples.
`CloudApiError`	`core/client.ts`	Error class thrown by `CloudApiClient` on non-2xx responses. Carries `.status` and the structured `{ error }` body verbatim; branch on `instanceof CloudApiError && err.status === 409` to handle slug collisions, etc.
`defaultArkorCloudApiUrl(credentials?)`	`core/credentials.ts`	Resolve the cloud API base URL the SDK should target. Priority: `ARKOR_CLOUD_API_URL` env var → the URL stored on the loaded credentials (anonymous credentials carry it from signup; OAuth credentials carry it since `arkor login` was updated to persist the auth-time URL) → the production endpoint. Use this when constructing a `CloudApiClient` from `readCredentials()` / `ensureCredentials()` so a script keeps targeting the same staging / self-hosted control plane the user authenticated against.

Types

Public type exports (from arkor):

Arkor, ArkorInput, ArkorProjectState, BlobDatasetSource, DatasetSource, HuggingfaceDatasetSource, JobStatus, LoraConfig, Trainer, TrainerCallbacks, TrainerInput, TrainingJob, TrainingResult, plus OAuthCredentials, AnonymousCredentials, and Credentials for the auth helpers.

Deployment-related type-only exports (see Deployments): CloudApiClientOptions, DeploymentTarget, DeploymentAuthMode, DeploymentRunRetentionMode, DeploymentDto, DeploymentKeyDto, DeploymentScope, CreateDeploymentInput, UpdateDeploymentInput, CreateDeploymentKeyInput, CreateDeploymentKeyResult. The runtime CloudApiClient and CloudApiError classes are listed under Utilities above; they're value exports, not types, so import them as values.

TrainingLogContext, CheckpointContext, InferArgs are not exported by name today; they are documented in the callbacks and infer pages so you can mirror them inline if you need typed callback parameters.

Not in the public surface

These exist in the source tree but are intentionally not exported from arkor. Treat them as internal: