---
title: "API reference"
description: "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
// 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
// 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)`](/docs/framework/sdk/create-arkor) | Project manifest. Wraps a `Trainer` so the CLI / Studio can find it. |
| [`createTrainer(input)`](/docs/framework/sdk/create-trainer) | The fine-tuning run definition: model, dataset, LoRA, hyperparameters, callbacks. |
| [`Trainer.start / wait / cancel`](/docs/framework/sdk/trainer-control) | Run-control methods. `wait()` is where lifecycle callbacks fire. |
| [`TrainerCallbacks`](/docs/framework/sdk/callbacks) | The five lifecycle callbacks (`onStarted`, `onLog`, `onCheckpoint`, `onCompleted`, `onFailed`). |
| [`InferArgs` / `infer`](/docs/framework/sdk/infer) | Inference inside `onCheckpoint`. Returns a raw `Response`. |
| [`DatasetSource`](/docs/framework/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`. `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`](/docs/framework/sdk/deployments) | `core/client.ts` | Typed client for the cloud API. Exposes `listDeployments` / `createDeployment` / `createDeploymentKey` etc. for managing `*.arkor.app` inference URLs. See [Deployments](/docs/framework/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 `OAuthCredentials`, `AnonymousCredentials`, and `Credentials` for the auth helpers.

Deployment-related type-only exports (see [Deployments](/docs/framework/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](/docs/framework/sdk/callbacks) and [infer](/docs/framework/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](/docs/framework/concepts/lifecycle) for what `start()` / `wait()` actually do
- [Project structure](/docs/framework/concepts/project-structure) for where the manifest and trainer live in a project
- [CLI overview](/docs/framework/cli/overview) for the surface that drives the SDK from the shell