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:

• SDK_VERSION: used by the CLI and Studio server for header / log purposes. Do not import via deep paths; the export contract may change.
• The CLI command runners (runBuild, runStart, runDev, runInit, runLogin, runLogout, runWhoami): they live under src/cli/commands/ and are CLI-private. If you need to drive a training run, use runTrainer (above) or call trainer.start() / trainer.wait() directly.

See also

• Run lifecycle for what start() / wait() actually do
• Project structure for where the manifest and trainer live in a project
• CLI overview for the surface that drives the SDK from the shell