Arcane OS SDK

arcane-os is the application SDK and command-line toolchain for Arcane OS. It supports two explicit workspace profiles: an external app repository uses the version-locked SDK runtime, while an integrated Arcane checkout consumes its selected SDK projection or an explicit live SDK source mount. Both profiles share the theme, packaging, event, cancellation, and browser run contracts while retaining their selected application layout.

This checkout defines the 0.97.1 SDK contract. Development applications declare arcane-os as latest and retain their lockfile. Exact SDK pins begin when Roshi designates a production build. Follow Consumer updates to refresh and compare the installed SDK and lockfile with the published channel; registry state is deliberately not baked into application artifacts.

Physical execution devices exposes Windows CPU/GPU/NPU discovery and native ONNX/Laya target selection through the existing Core host, independently of model loading. Device presence, configured provider placement and observed model execution remain separate facts.

Standalone browser apps use their repository root and installed npm package directly, without a generated workspace arcane/ directory or arcane.lock.json. Select the four installed-package routes in arcane-packager.json: development, managed import maps, and PWA resources read the installed SDK at real /node_modules/arcane-os/... browser URLs when each destination equals its source. An alias uses its actual installed folder. arcane new my-app defaults to appsRoot: ".". After npm installation, arcane import-map refreshes managed maps and the enabled root PWA files for ordinary static hosting. It generates no nested app redirects or duplicate PWA files. Remove the retired legacyAppPaths setting when upgrading. Commit generated and offline app files for hosting workflows to consume. Portable app packages still contain their selected runtime. Root/direct maps use arcane-os/modules/<filename> and arcane-os/entities/<filename> (including extensions) plus the focused lowercase exports, rather than arcane/* aliases. These paths resolve to the actual npm files, preserving relative component URLs. New root apps put the SDK in runtime dependencies; init preserves existing runtime/optional declarations and promotes a root app's SDK development declaration without changing its other packages. Explicit multi-app appsRoot: "apps", virtual runtime routes, and existing materialized workspaces remain supported; initialization preserves their selected layout. Node services continue to use the installed CLI or public imports such as arcane-os/mail.

The mail gateway serves HTTPS with HTTP/2 on port 4433 by default. Configure its host, port, origin list, certificate paths, and other mail settings in arcane.config.json.mail; keep provider keys in the ignored .arcane.env.json.mail. Both files belong in the command's working directory. Existing root credential, profile, and TLS settings remain supported. Browser mail defaults to /v1/mail on the current domain, and multiple applications can share one server with explicit allowed origins. Subscription verification is disabled until a verifySubscription callback is configured; that callback receives the application name and bearer subscription key before provider attempts from other requester IPs. Requests whose actual connection source IP equals the server-side IP of that connection automatically skip subscription verification, including local development. Other intranet machines still need verification. The exception requires no environment setting or domain lookup. See the method and action gate report for the removals, retained responsibilities, and naming decisions.

Applications can enable PWA installation and offline resources through their app descriptor. The SDK generates manifests, an independent registration module and a service worker, with clean browser resource URLs, page-load revalidation and persistent resource caches. The SDK records one completed-check timestamp per app/cache in DBOPFS and checks after 120 seconds in development or 15 minutes in packaged browser delivery. Apps retain ownership of branding, offline page selection and network-dependent product behavior. Enabled browser delivery also mounts the shared, themed installation suggestion. It appears when the browser offers installation, includes Install and Close, and remembers dismissal for the tab session without interrupting page startup.

Registry queries are maintainer actions. Apps never poll npm for SDK updates or replace their own SDK or synchronized runtime. The app repository's exact dependency and lockfile select the SDK; changing that selection is an explicit repository update. Tests and checks run only when the user expressly selects them, or when required for a selected release output.

Current capabilities

| Build this | Start here | | --- | --- | | A standalone browser app with shared theme, components, source serving and PWA resources | Beginner quick start, CLI, PWA | | Streaming or complete AI responses, structural tools and a model selected for one request | AI runtime, TWiN Cloud | | Stateless state-and-questions evaluation or image generation | fetchSystemOneRequest, generateImages | | Browser-local language models with an application-owned model catalog | Browser-WASM AI | | Local Whisper/Kokoro, native browser recognition and voices, or selected cloud speech | Speech provider guide | | Editable live transcription, ordered speech playback and printed conversations | Chat, SpeechPlayback | | Complete saved conversations, request-only turns, document retrieval and stored Markdown images | Chat sessions, document library, MarkdownMedia | | Windows, Linux or Android development output from the same app | Native target matrix |

Provider and platform availability are documented at each surface. Applications own model selection, credentials, prompts, saved data and product behavior.

Beginner quick start

Create one browser application, install its pinned SDK, and start its source server:

npx arcane-os@latest new hello-speech --path ./hello-speech --target browser
cd hello-speech
npm install

Configure the workspace's HTTPS certificate pair as described in development HTTPS setup, then start:

npm run dev

To open a selected app from another device on the network, append --public to the same command:

npm run dev -- --app hello-speech --public

Replace hello-speech with any app in the workspace. The server binds to 0.0.0.0 and serves HTTPS using .arcane/dev/server-cert.pem and .arcane/dev/server-key.pem in the workspace. Supply a certificate covering the LAN address or hostname you will open, and trust its issuing development CA on each device. Keep these local files ignored by Git. The same certificate pair works for any selected app in that workspace. The command reports missing TLS files instead of starting an HTTP listener.

HTTPS is the default for development and packaged browser previews. Plain npm run dev binds to localhost with the same workspace certificate pair. An explicit --host overrides the bind address, and --port selects the HTTPS port. The paired HTTP listener returns 308 redirects and uses an OS-assigned port unless selected with --http-port. The command prints its redirect URL. Use --cert <file> --key <file> for an explicit PEM pair; relative paths resolve from the workspace. The server prints HTTPS network URLs for public mode. Network reachability depends on the machine's firewall and network. See the development HTTPS setup for device trust and DBOPFS's secure-context requirement.

For explicit HTTP source development, including LAN device testing, use:

npm run dev -- --app hello-speech --public --http --port 8000

This selects one HTTP content listener and prints HTTP network URLs. It reads no certificate pair and serves the same application and generated PWA routes. PWA and storage availability still depend on the browser's secure-context rules; see HTTP development. API callers may also explicitly select http:true with mode:'packaged' to serve the selected packaged web root through the same listener owner. See startDevServer() for readiness, start-URL and shutdown behavior.

Open the URL printed by the server. The generated page owns its import map and Arcane theme; its application module is modules/App.js at the repository root. Root applications use managed arcane-os/* browser imports. Importing arcane-os/ai resolves the shared AI module; its browser lifecycle still requires the documented browser environment. For a stateless Node request, use arcane-os/ai/twin-cloud.

For a first spoken sentence, copy the application-owned speech-selection.js configuration from the speech quick start beside App.js, then use this module. That one configuration file defines the upstream runtime, model, dtype, and voice. This module creates the application's DBOPFS store; the SDK creates and manages its speech providers and Workers. The linked automatic NPU/GPU/CPU selection uses fp32 because Kokoro.js recommends fp32 when using WebGPU. Its selectedDevice status reports the loaded route, not speech correctness or audio quality.

import arcaneThemeReady from 'arcane-os/modules/ThemeBootstrap.js';
import AI, { AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL } from 'arcane-os/ai';
import DBOPFS from 'arcane-os/modules/DBOPFS.js';
import { speechSelection } from './speech-selection.js';

await arcaneThemeReady;
const dbopfs = new DBOPFS();
await dbopfs.readyPromise;
const ai = new AI();
await ai.configureBrowserSpeech({
  protocol: AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL,
  id: 'hello-speech',
  dbopfs,
  tts: {
    providerId: 'hello-kokoro',
    model: speechSelection.model,
    runtime: speechSelection.runtime,
    offline: false
  }
});

const button = document.createElement('button');
button.textContent = 'Load voice and say hello';
document.body.append(button);
button.addEventListener('click', async function sayHello() {
  button.disabled = true;
  try {
    await ai.setSpeechMuted(false);
    console.log(ai.providerRuntime.status('tts', { execution: true }).execution);
    const prepared = await ai.streamTTS('Hello from Arcane. ', true);
    console.log('Speech preparation completed:', prepared);
  } catch (error) {
    console.error(error.code, error.message);
  } finally {
    button.disabled = false;
  }
});

The button explicitly loads/unmutes the selected model and requests speech. The first load can download the app-selected runtime/model/voice; the browser may need another audio-unlock gesture after a long load. Keep the complete visual response available alongside speech.

Capacity 4 means up to four segments synthesize at once. Segment 5 and later wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of order, but playback waits for earlier segments and plays exact input order. Each slot owns a Worker/model session, so raising capacity trades memory for latency.

If your app already has complete segments in an array, let the shared SpeechPlayback owner submit them as soon as they are available:

import SpeechPlayback from 'arcane-os/speech-playback';

const audio = document.body.appendChild(document.createElement('audio'));
audio.controls = true;
const narration = new SpeechPlayback({
  audio,
  speech: ai,
  onState(detail) {
    console.log('Speech state:', detail.state);
  }
});
const speakAll = document.body.appendChild(document.createElement('button'));
speakAll.textContent = 'Speak all segments';
speakAll.addEventListener('click', async function speakAllSegments() {
  await ai.setSpeechMuted(false);
  await narration.prepare({
    parts: ['First segment.', 'Second segment.', 'Third segment.'],
    autoplay: true
  });
});

With browser speech's default auto / 4 configuration, all three complete segments enter the provider queue immediately, up to four synthesize at once, and the audio still plays first, second, third. Native or custom speech without advertised provider execution capacity stays serialized with one lookahead.

Existing speech controls can also import the shared compatibility catalogs. They list the ten existing value/label choices but do not choose a voice for the application or prove that a selected provider supports one:

import {
  SPEECH_VOICE_ALIASES,
  SPEECH_VOICE_OPTIONS
} from 'arcane-os/speech-playback';

console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}
console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true

Continue with streaming chunks, device selection, cancellation, status, and cleanup, the tiny TWiN Cloud request and saved-preference migration, or the maintained WASM voice-chat example. The installed package also includes docs/ and the maintained example source: open node_modules/arcane-os/docs/reference/ai/browser-speech.md, node_modules/arcane-os/docs/reference/ai/twin-cloud.md, or node_modules/arcane-os/examples/wasm-ai-demo/README.md locally. Public links above work from both npm and GitHub.

Developer API reference

Start with the capability-first developer reference. It follows Arcane's MDN-style model and covers every public package export, CLI command, synchronized runtime module, entity, component, Arcane Core member, and Arcane Ollama method. Use the availability and normalization matrix to distinguish Node, browser, native, cloud, and cross-host behavior; protocol mechanics are kept in the folded/deep-linked protocol guide. The behavioral-testing guide explains the executable contract, while the machine-readable inventories make completeness independently checkable.

Central event instrumentation

Use arcane-os/event-manager as the primary instrumentation surface for new SDK code. Its shared arcaneEvents bus is powered by event-pubsub; SDK-owned operation queues already mirror their normalized events through it while preserving awaited delivery and cancellation. An opt-in timeTravel flag adds complete timestamped causal event stacks, export/import, seek and safe review playback. Attaching a DOM root records interactions and mutation records, including supported open shadow roots. Source-stack capture is a separate, off-by-default diagnostic option.

Recording is off by default. Once explicitly enabled, a session retains its complete recorded content until the caller clears it or disables recording. Review the EventManager guide before enabling DOM values, node content, event details, source stacks, or live event redispatch. Password targets, text-entry details, clipboard data, URL attributes, and common credential keys are excluded or redacted by default.

Runtime source ownership

The SDK repository is the canonical source for portable shared runtime modules, entities, components, themes, browser providers and workers, public contracts, and their packaged content. Portable applications consume those SDK-owned paths and never read an Arcane OS install or source checkout at runtime. Arcane OS is a consumer of this contract; its repository-side cutover is coordinated separately and cannot become a second source authority.

The source-authority cutover is complete. runtime/arcane/ is authored here, and applications copy the complete portable inventory selected by the package. Arcane OS must consume the same locked SDK projection as other applications; an OS-side duplicate is consumer projection state, not source authority. Git history records the completed source-authority migration; the current tree has no OS-to-SDK synchronization command or migration-only runtime-source record.

TWiN Cloud

TWiN Cloud is the SDK's default remote language-model service, identified by TWIN. It sends chat-completion requests to https://inference.do-ai.run/v1/chat/completions with model openai-gpt-oss-120b. Supply the bearer credential through ai.twinKey or globalThis.arcane.config.twinCloud.accessKey. The established ai.license property remains available. Applications should present the service and credential as TWiN Cloud and TWiN access key. Explicit cloud speech, System One and image requests also use application-supplied credentials. The built-in local speech selections remain Whisper (LOCAL_SPEACH / whisper-small) for transcription and Kokoro (LOCAL_SPEACH / kokoro) for synthesis. Those local routes use no TWiN key. Applications may separately select native browser speech or TWiN Cloud TTS; browser-native services may process speech remotely.

The built-in provider and default-model preference sentinel are both TWIN. Applications upgrading saved preference tuples must replace only uppercase OPENAI in slot 0 (LLM provider) and slot 3 (default-model sentinel) with TWIN through the existing application preference owner before importing AI.js or any module that imports it, and before AI preference hydration. Use dynamic import after migration; module evaluation can instantiate AI immediately when the user is already ready. Keep every other value unchanged, including openai-gpt-oss-120b and openai-gpt-oss-20b. The SDK provides no built-in OPENAI alias and does not rewrite saved preferences. OpenAI-compatible wire terminology and the separate Core provider:'openai' contract are unchanged. The TWiN quick start and migration recipe show the exact application-owned operation.

fetchRequest() and streamRequest() accept the provider-neutral reasoningEffort option with none, low, medium, high, or max. TWiN Cloud maps it to DigitalOcean Serverless Inference reasoning_effort; omitting it preserves the provider default. TWiN Cloud defaults to openai-gpt-oss-120b, and applications may explicitly select openai-gpt-oss-20b without changing streaming or structural-tool behavior. An explicit request model selects that call's model without changing saved preferences. The stateless fetchRequest, fetchSystemOneRequest and generateImages exports in arcane-os/ai/twin-cloud require a caller-selected model and return the complete documented provider result. They retain no chat history. See the TWiN Cloud guide for each request shape, diagnostic callbacks, cancellation and image-job behavior.

Browser-local AI

arcane-os/ai/browser-wasm provides the shared Wllama LLM provider. The app supplies its model catalog; the SDK does not hard-code Granite or any other app profile. Each descriptor uses one ordered files array, so monolithic and split GGUF models share the same contract:

import { createBrowserModelSource } from 'arcane-os/ai/browser-wasm';

const source=createBrowserModelSource({
    id:'app-model',
    files:[
        {name:'model-00001-of-00002.gguf',url:'https://models.example/one.gguf'},
        {name:'model-00002-of-00002.gguf',url:'https://models.example/two.gguf'}
    ]
});

Model members require only their names and URLs. A member may also declare a positive safe-integer bytes value so the application can present determinate progress and the transport can plan parallel HTTP ranges. An unusable value is treated as unavailable and never blocks the ordinary download. That value is observational transfer metadata: it never validates, admits, identifies, or decides cache reuse for model content. During a cache miss, the store reports live aggregate loadedBytes, totalBytes, remainingBytes, bytesPerSecond, etaSeconds, activeTransfers, transferLimit, and transferMode alongside the existing completed-file counts. Chunk-driven updates are coalesced on a 250 ms cadence; transfer-plan, active-worker, and completion boundaries publish immediately. Optional hardening is inactive unless the caller explicitly selects secure:true. The DBOPFS store downloads ordered members with one bounded parallel transfer pool and returns them in descriptor order. Completed shards survive an interrupted attempt and only missing shard or Range-part work is fetched on retry. A monolithic file uses up to downloadConcurrency active workers (four by default) over deterministic, resumable HTTP range parts of roughly 4 MB each, up to 4,096 parts, when the server confirms 206 responses and the total comes from Content-Range or, when that header is not exposed, optional declared bytes. When a followed redirect turns the first Range probe into 200, the SDK probes the final URL directly before reusing that original response as the single-fetch fallback. Completed range parts survive restart and are presented to Wllama as one logical model. Split members use the same Range negotiation with one active Range worker per member, so completed parts within a shard can also resume without multiplying the configured transfer bound. A probe without an observable or declared total falls back to one full fetch. Once a complete whole file or Range set is available, the store removes superseded fragments when DBOPFS deletion succeeds; cleanup failure is warned without hiding the usable model. Capability reports evaluate each app-supplied model as compatible, incompatible, or unknown; the app can render that result without the SDK inventing or filtering its catalog.

arcane-os/ai/browser-speech exposes independent Whisper STT, Kokoro TTS, native browser recognition, native browser synthesis and TWiN Cloud TTS provider factories. The local-model path contains the plain-JavaScript provider and Worker machinery, not speech runtimes, models, voices, or a CDN default. An app must supply each runtime/model selection explicitly. Speech roles load, cancel, unload, fail, and recover independently, so speech failure never switches to a cloud provider or prevents text chat. Both roles default to NPU, GPU, then CPU automatic selection: WebNN NPU when its browser API is exposed, then WebGPU, then WASM. Failed model loads release their Workers before the next backend uses the same model and precision. Apps may select webnn-npu, webgpu, or wasm explicitly without automatic fallback. Whisper keeps one transcription slot; Kokoro defaults to four Worker/model sessions and accepts capacities from one through four. Both roles expose requested and selected devices through execution status. A selected backend reports successful upstream loading, not physical accelerator use for every operation; model and hardware compatibility remain upstream.

Native speech requires the browser's actual recognition or synthesis API. Voice discovery and preparation are silent; explicit playback owns completion, pause, resume, cancellation and release. provider.setDefaultVoice(voiceURI|null) changes future native preparations while preserving explicit choices and already prepared speech. ai.prepareTTSPlayback(payload,signal) returns a native playback descriptor or real Blob audio; fetchTTS() and durable prepareTTS() require real audio and report native audio-export unavailability. Cloud TTS queues complete jobs and preserves original-order playback. See the speech guide for voice catalogs, recognition language and provider-specific limits.

Applications that need faster spoken-response onset can configure the shared TTS stream without taking over synthesis or playback:

ai.configureTTSSegmentation({
    punctuation:'any',
    wordCadence:null
});

The compatibility default remains sentence punctuation with no word cadence. Within the already prepared speech text, the configured segmentation preserves every character and punctuation mark, chooses the earliest complete boundary, begins synthesis as each segment becomes available, and plays the completed audio in exact segment order. Ready adjacent buffers are scheduled consecutively on the browser audio clock rather than waiting for an ended callback before the next start. Any-punctuation mode recognizes boundaries without requiring whitespace while keeping apostrophes, commas, and hyphens that join Unicode letters or numbers inside the same segment. Mute, stop, provider transition, and cancellation still govern the whole queue.

TTS narration removes repeated same formatting marks (*, #, _, backtick, ~) from its outbound speech-input copy before synthesis. Streaming calls also recognize a run split across chunks. Single marks and ordinary repeated punctuation remain literal. Complete synthesis calls may select textFormat:'plain' to preserve exact input: supply it in prepareTTS options or the payload of fetchTTS, provider-runtime TTS requests, or direct Kokoro requests. The SDK consumes this control before engine/host dispatch; omission keeps the default cleanup. SpeechPlayback accepts the same option in its constructor or prepare() call and forwards each part's exact input. Streaming narration retains its existing formatting behavior. This option does not change the selected engine's input capacity or establish complete upstream synthesis. Original messages and caller payloads remain unchanged for display, storage, and model input. The arcane-os/speech-text entrypoint exports the same MarkdownSpeech streaming class and stripSpeechFormatting() one-pass helper for code that needs the speech-only transformation directly.

The SDK runtime also owns DBOPFSDocumentLibrary, DocumentLexicalSearch, and PersistentAIChatSession. Document bootstrap is schema-driven and explicit; chat never searches a corpus unless the app wires that library into the request context builder. Persistent chat automatically maintains recurring model context and ChatEntity history/memory. A turn may set persist:false to participate in one request and response only; after that operation settles, neither side remains in subsequent model context, the retained transcript, durable chat, memory, or DBOPFS. For an automatic model-authored opening, call session.open({message:{content:bootstrap,persist:false}}): the bootstrap is request-only, while the complete nonblank assistant response becomes the first durable conversation row without a fabricated user turn. createArcaneAI(...).createChatSession(options) wires that session to the same selected LLM controller, creates its ChatEntity, and uses the same controller for automatic memory extraction.

Install

Create a standalone Arcane application from the current stable SDK. The scaffold records the selected exact version:

npx arcane-os@latest new my-app --path ./my-app --target browser --git
cd my-app
npm install
# Configure HTTPS as described above, then start source development.
npm run dev

To enroll an existing repository, install the exact SDK and initialize only missing Arcane files:

npm install --save-exact arcane-os@latest
npm exec -- arcane init my-app --target browser

The npm package is named arcane-os. Its primary executable is arcane, and arcane-os is an equivalent fallback when another globally installed package has claimed the short command:

npm exec -- arcane targets
npm exec -- arcane-os targets

No global SDK install or standalone Arcane CLI is required. The application repository's exact npm dependency and lockfile own the CLI and toolchain version.

Use npx arcane-os@latest for the initial bootstrap because it names this npm package explicitly; bare npx arcane outside an installed project could resolve a different package. Both installed commands invoke the same headless toolchain. Project-local npm scripts use the SDK pinned by that app's package-lock.json, so normal repository work does not depend on whichever global command was installed last.

Local development when the npm package is unavailable

Pack the current SDK checkout, scaffold with its source CLI, and persist the tarball install in the app's package manifest and lock:

# From the arcane-os-sdk checkout
npm ci
npm run pack:local
node ./bin/arcane.mjs new local-app --path ../local-app --target browser --git

# From the generated app repository
cd ../local-app
npm install --save-exact "../arcane-os-sdk/arcane-os-<selected-version>.tgz"
npm ci

Adjust the relative tarball path for your layout and keep that .tgz at the same location. The lockfile retains the selected package dependency while Arcane uses the installed package name and version. Local directory file: dependencies are not accepted because npm may install them as links; use a packed .tgz. A GitHub runner also needs that tarball at the locked path. After publication, replace the local declaration with the selected exact registry version and commit the regenerated lock.

Generated repositories use npm ci --ignore-scripts in CI. Run dependency installation once and commit package-lock.json before enabling that workflow.

Integrated Arcane OS development

Run the same SDK against the Arcane OS checkout when changing a shared runtime capability or a built-in app. During local SDK development, invoke its source CLI explicitly so Arcane OS does not acquire an npm self-dependency:

node ../arcane-os-sdk/bin/arcane.mjs check --workspace "../Arcane OS" --app calculator
node ../arcane-os-sdk/bin/arcane.mjs dev --workspace "../Arcane OS" --app calculator
node ../arcane-os-sdk/bin/arcane.mjs package --workspace "../Arcane OS" --app calculator

arcane init new-app --workspace <arcane-root> --target portable detects the integrated profile and writes only apps/new-app/ boilerplate. It does not modify Arcane OS root scripts, dependencies, workflows, lock files, or repository instructions.

Shared runtime and Core work has an explicit integrated-only scope. Select one exact focused test, or run Arcane's canonical development check through the fixed Arcane-owned provider:

node ../arcane-os-sdk/bin/arcane.mjs test --workspace "../Arcane OS" --scope shared --test-file test/component-contracts.test.mjs
node ../arcane-os-sdk/bin/arcane.mjs check --workspace "../Arcane OS" --scope shared

The default scope is app. Shared scope never discovers, packages, verifies, builds, or runs an application, and it is rejected in an external workspace. The provider admits only one repository-relative .test.mjs through Arcane's focused runner or the one canonical development check; it cannot select an arbitrary command or package script.

In an integrated Arcane checkout, app scope runs tests only under the selected apps/<id>/test/ tree and reports an honest skip when that tree has no tests. Arcane root, shared, and native tests require the explicit shared focused-test form above. External app repositories retain their root test/ plus selected app-test behavior.

Integrated native app builds select one --app and one declared native target, and --output-root must resolve outside that checkout. An explicit --arcane-root must resolve to the same Arcane checkout as --workspace; the default portable provider instead comes from the installed SDK package. The SDK then uses the same package, plan, provider, and same-process run lifecycle as an external app repository. Verification remains an explicit operation for a selected release output.

Commands

arcane new <id> [--path <directory>] [--display-name <name>] [--target <target>] [--git]
arcane init [id] [--workspace <directory>] [--display-name <name>] [--target <target>]
arcane doctor [--workspace <directory>] [--arcane-root <directory>]
arcane import-map [--workspace <directory>] [--app <id>]
arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000]
arcane test [--app <id>] [--scope app]
arcane test --scope shared --test-file <repo-relative.test.mjs>
arcane check [--app <id>] [--scope app] [--skip-tests]
arcane check --scope shared
arcane package [--app <id>] [--dry-run]
arcane verify [--app <id>]
arcane bundle [--app <id>] [--artifact <file>.arcane-app.tar.gz] [--overwrite]
arcane verify-bundle <file.arcane-app.tar.gz>
arcane native-doctor --target <native-target> [--arcane-root <directory>]
arcane native-prepare --target <native-target> [--arcane-root <directory>]
arcane build --target <target> [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
arcane run [--target <target>] [--app <id>] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
arcane targets
arcane repo status|pull|push

All commands support --output human|json|ndjson. Machine modes keep stdout structured. Every operation emits or reports acceptance before filesystem, network, explicitly requested test, process, or service work begins.

External application release bundles

An authored schema-2 arcane-app.json can be bundled with one already packaged browser release. The bundle contains only the canonical descriptor, the release manifest, and the complete selected dist/<id>/ payload inventory:

npm exec -- arcane package --app my-app
npm exec -- arcane bundle --app my-app
npm exec -- arcane verify-bundle dist/my-app-1.0.0.arcane-app.tar.gz

bundle creates dist/<id>-<version>.arcane-app.tar.gz by default. It refuses an existing destination unless --overwrite is explicit and preserves the prior file until the replacement is complete. Cancellation or failure before commit restores the prior output when that can be done without overwriting a concurrent change. A conflicting or uncertain path is preserved for inspection.

The archive uses USTAR+gzip with per-file PAX path extensions for long or non-ASCII filenames and publishes its v1 JSON contract at arcane-os/schemas/arcane-app-bundle.json. Logical filenames and content remain complete; ordinary USTAR paths retain their existing representation, and bundle metadata keeps its existing SDK-version matching contract. Readers must support PAX path extensions to consume bundles that need them. When the user explicitly selects bundle verification, it rejects malformed archives, links, devices, unsafe or colliding paths, unsupported archive members, trailing data, and inconsistent descriptor or inventory structure. These checks reject corrupt selected artifacts; they do not impose byte-count, hash, provenance, or admission gates on ordinary development, packaging, serving, or running. Portable path validation rejects file/directory prefix conflicts, case-colliding prefix spellings, and Windows device aliases including superscript COM/LPT digits.

Use the public package and bundle commands for the selected app output. The checked-in reusable release-app.yml workflow still pins an older SDK and is outside the current supported release path. See publication scope before selecting a repository release workflow.

SDK test sets

The repository suite uses exact vanilla-test 2.1.3 through the isolated Arcane test runner. npm test runs four non-overlapping sets in order, and every test file belongs to exactly one set:

npm run test:unit
npm run test:functional
npm run test:integration
npm run test:regression

Run a named set or npm test only when explicitly selecting that verification, or when required for a selected release output. Large fixtures stay inside one isolated file process and expose smaller nested cases, so the report shows the individual behaviors without repeating setup, builds, package installation, or assertions.

Current target support

The SDK exposes one browser target and an SDK-owned, non-runnable portable payload directory. Four executable target entries require an explicit Arcane OS provider: a Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64 unsigned-local-test DEBs, and an Android development-signed APK. The android-arm64 APK is architecture-neutral because it contains no native ABI; the target name identifies its supported physical/native ARM64 run profile.

Portable uses the installed SDK provider without an Arcane OS checkout. An explicit --arcane-root retains the checkout provider selection; executable targets still require that root and their platform toolchains. Every native build needs a canonical app descriptor declaring the exact selected target. The SDK never searches for a mutable toolchain root. Scaffold a separate repository with the matching --target, or add and validate that target in the canonical descriptor before invoking its native command. From an external application repository, run one selected target:

npm exec -- arcane native-doctor --target portable
npm exec -- arcane build --target portable

# Windows x64: build or build, verify, and launch in one process
npm exec -- arcane build --target windows-x64 --arcane-root "../Arcane OS"
npm exec -- arcane run --target windows-x64 --arcane-root "../Arcane OS"

# Linux x64, from Linux or WSL with the documented GTK/WebKit toolchain
npm exec -- arcane build --target linux-x64 --arcane-root "../Arcane OS"
npm exec -- arcane run --target linux-x64 --arcane-root "../Arcane OS"

# Linux ARM64, on a compatible native ARM64 toolchain
npm exec -- arcane native-doctor --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
npm exec -- arcane build --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
npm exec -- arcane run --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test

# Android ARM64; run requires one connected physical/native ARM64 device
npm exec -- arcane native-doctor --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
npm exec -- arcane build --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
npm exec -- arcane run --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development

Use --target portable, windows-x64, linux-x64, linux-arm64, or android-arm64 when scaffolding to include the required raster icon and declare both browser and the selected native target in the canonical app descriptor. The browser remains available from the same repository. A native command does not infer a missing descriptor target from --target and never substitutes a browser package.

native-prepare is available as a standalone toolchain diagnostic. Do not run it automatically: the build command prepares the selected toolchain itself.

The build passes the complete selected app release, descriptor, dependencies and minimum Core requirement to the provider. The SDK portable provider copies those payloads and generates a Core entry and synchronous classic client. Explicit application services use createPortableNativeProvider({services:[{module,options}]}) from arcane-os/native/portable-provider; the default imports no OS product or application services. arcane-os/core/host owns reusable native service composition and shutdown. See Core native packaging. Payload assembly is separate from composed-host compatibility and execution. The portable payload under build/portable/ is not executable and arcane run --target portable is intentionally unavailable. No executable host, installer, model assets or platform build toolchain is added by this SDK provider. Through explicit Arcane OS providers, Windows emits an app-scoped executable bundle under build/windows-x64/. Linux emits an app-scoped amd64 DEB under build/linux-x64/ or ARM64 DEB under build/linux-arm64/. Android emits one development-signed, architecture-neutral APK under build/android-arm64/; there is no native ABI payload, and its run path requires a physical device with native ARM64 support. Executable run performs package, prepare, plan, build, launch, and owned cancellation in one process. Verification occurs only when explicitly selected for that release output.

The Windows x64 and Linux x64 paths have been exercised end to end from independent external repositories. Windows compiled, verified, reached an authenticated readiness channel, and cancelled an isolated development app while a valid installed publisher-continuity pin remained present. Linux x64 built and verified a real DEB and launched it under WSLg without installation or sudo.

At the recorded Arcane source revision, the native ARM64 workflow built an ARM64 DEB, exercised its AArch64 host, Core, and bridge, reached WebKit load-finished readiness, and drained its owned process group. The workflow kept Ubuntu's AppArmor user-namespace restriction enabled and loaded the packaged Bubblewrap profile. The recorded Android development path exercised build, readiness, cancellation, uninstall, and absence behavior on a physical ARM64 device. These are development results, not production signing, store-publishing, release, or promotion evidence.

| Capability | Ready now | |---|---| | Scaffold, develop, test, check, package, verify, and browser run | Yes | | External proprietary-source repository workflow | Yes, subject to the distribution license below | | Integrated Arcane checkout workflow | Yes | | ArcaneOllama managed-service check | Yes on supported Windows hosts | | SDK native plan/provider boundary | Yes | | Portable app-scoped payload and reusable Core entry | SDK provider by default; explicit checkout override retained; not directly runnable | | Windows x64 EXE bundle | Yes, unsigned local development with explicit --arcane-root | | Linux x64 DEB | Yes, unsigned local development with explicit --arcane-root | | Linux ARM64 DEB | Yes, unsigned local development on a compatible native ARM64 toolchain with explicit --arcane-root; native build, WebKit readiness, and cancellation evidence is recorded | | Android ARM64 APK | Yes, development-signed and architecture-neutral with explicit --arcane-root; a physical/native ARM64 device is required for run |

Android supports APK only in this development profile. AAB, release signing, publishing, and update continuity remain deferred. Unpaired, incompatible, or descriptor-mismatched native requests fail without producing a substitute artifact. Portable output is never represented as an executable, and unsigned or development-signed evidence is never represented as production signing or release acceptance.

See docs/platform-targets.md for the matrix and docs/architecture.md for the boundary. The exact minimum-version and required-contract compatibility rule is documented in docs/compatibility.md. The issue-ready extraction sequence is tracked in docs/roadmap.md.

Canonical app descriptor

New standalone apps own root arcane-app.json schema 2; explicitly selected multi-app layouts use apps/<id>/arcane-app.json. It contains publisher, optional permissions and security declarations, native presentation, optional Core requirements, and target intent, and deterministically projects the schema-1 arcane-package.json required by the current browser packager. The pinned schema-1 apps recognized by this SDK are accepted through a read-only projection of the current native registry until each app adopts the authored descriptor. The schema-1 release manifest is intentionally unchanged during this migration; that current projection is not a general future-compatibility guarantee.

ArcaneOllama

Browser development never calls Ollama directly. arcane doctor performs a read-only managed-service assessment where the host supports one. Native apps use an app-scoped Arcane Core and Arcane.localAI.status() in this SDK version. Ollama is optional for packaging and non-AI applications.

The development server serves complete selected files and does not apply byte-count or truncation gates. Optional hardening is inactive unless the caller explicitly selects secure:true. Required credential protection, malformed-request rejection, and unavoidable browser or operating-system safety remain in effect. Declared origins remain native policy input only when the app explicitly authors them.

Licensing

The synchronized Arcane runtime and packager are currently distributed under AGPL-3.0-only. The commercial-license notice does not itself grant proprietary distribution rights. Resolve the applicable Arcane commercial or open-source license before distributing a closed-source app that bundles this runtime. Each browser release carries LICENSE, COMMERCIAL-LICENSE.md, and NOTICE at the configured SDK package route: node_modules/<dependency>/ for direct installed routes, or licenses/arcane-os/ for a configured physical runtime layout. The notice includes the complete bundled Marked and QRCode.js MIT terms.