> ## Documentation Index > Fetch the complete documentation index at: https://arkor-92aeef0e-eng-615.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```ts theme={null} // 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, }); ``` ```ts theme={null} // 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)`](/sdk/create-arkor) | Project manifest. Wraps a `Trainer` so the CLI / Studio can find it. | | [`createTrainer(input)`](/sdk/create-trainer) | The fine-tuning run definition: model, dataset, LoRA, hyperparameters, callbacks. | | [`Trainer.start / wait / cancel`](/sdk/trainer-control) | Run-control methods. `wait()` is where lifecycle callbacks fire. | | [`TrainerCallbacks`](/sdk/callbacks) | The five lifecycle callbacks (`onStarted`, `onLog`, `onCheckpoint`, `onCompleted`, `onFailed`). | | [`InferArgs` / `infer`](/sdk/infer) | Inference inside `onCheckpoint`. Returns a raw `Response`. | | [`DatasetSource`](/sdk/dataset) | 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`. `ensureCredentials` returns the existing record if present and **bootstraps a fresh anonymous identity** (calls `requestAnonymousToken` and persists it) when no credentials exist. Throws on a few paths: the credentials file exists but is unreadable / not valid JSON (`readCredentials` does a bare `JSON.parse`), or the anonymous-token bootstrap itself fails (network / token-endpoint error). 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`](/sdk/deployments) | `core/client.ts` | Typed client for the cloud API. Exposes `listDeployments` / `createDeployment` / `createDeploymentKey` etc. for managing `*.arkor.app` inference URLs. See [Deployments](/sdk/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 `Auth0Credentials` (the OAuth credentials type, named after the underlying Auth0-based provider), `AnonymousCredentials`, and `Credentials` for the auth helpers. Deployment-related type-only exports (see [Deployments](/sdk/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](/sdk/callbacks) and [infer](/sdk/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](/concepts/lifecycle) for what `start()` / `wait()` actually do * [Project structure](/concepts/project-structure) for where the manifest and trainer live in a project * [CLI overview](/cli/overview) for the surface that drives the SDK from the shell