Skip to content
tansr 资料站

Getting started: pick a path, run in 5 minutes

tansr is an agent runtime: one kernel (query loop, tool scheduling, permission engine, context compaction) offered in several different forms. You do not need to learn all of them. Pick one path based on “where do I want the agent to run”. The neutral bridge, the Harness, how Skill differs from the runtime, the current two steps, and the roadmap that is not offered yet are on Technical stance. The same statements, for a coding assistant to collect, are in /llms.txt. The homepage keeps only a collapsed entry at the bottom.

First question: where does the agent run?

Section titled “First question: where does the agent run?”
Your situation Recommended entry point Article
I want to talk to an agent in my terminal, edit code, run scripts the tansr CLI CLI in 5 minutes
I am writing a Node.js / Electron program and want to embed the agent in my own process @tansr/sdk Node SDK in 5 minutes
I want to offer an agent to my own mobile or web users and need a multi-user backend the @tansr/serve self-hosted session service Session service in 5 minutes
I am writing an Android app and the backend uses (or will use) @tansr/serve Kotlin SDK com.tansr.sdk (0.4.0) Android and iOS in 5 minutes
I am writing an iOS / macOS app, backend as above Swift binary package tansr-ios-spm (0.3.0) the “Same on iOS” section of the same article
I am writing a native HarmonyOS app, backend as above ArkTS HAR @tansr/harmony HarmonyOS SDK in 5 minutes

Two rules of thumb:

  • Solo use: the CLI. Building for others: the SDK or the session service. The CLI is for you as a developer; the SDK and the session service are for your product’s users.
  • Mobile always goes through your own backend. The Android / iOS / HarmonyOS SDKs are thin protocol clients that never hold any platform credential; the agent kernel runs inside the @tansr/serve you deploy. Devices that only run the Android-compatible HarmonyOS stack keep using the Android SDK.

The account model shared by all six paths

Section titled “The account model shared by all six paths”

Whichever path you take, credentials come in three layers, and the further down the list, the less they may ever leak:

  1. Personal access token (PAT): created by you in the console, used only by tansr init to sign the CLI in on your machine. It represents you.
  2. App key (appid / appkey): issued by you in the console for an “app”. The appkey lives only on your backend (a Node process or @tansr/serve) and is used to mint short-lived tokens for your end users. The appkey is never shipped to end-user devices, never logged, never committed.
  3. Short-lived app_user token: minted by your backend with the appkey and handed to the client (an Electron main process, or held internally by @tansr/serve). It expires; a leak is bounded by its TTL.

CLI users only need layer 1; SDK and session-service developers need layers 2 and 3. Placement and rotation advice is in Security and privacy.

Every getting-started article follows the same skeleton

Section titled “Every getting-started article follows the same skeleton”

The five form articles (Android and iOS share one; HarmonyOS has its own) unfold in the same order so you can compare forms side by side:

  1. Prerequisites: runtime and version requirements (Node ≥ 22.19 is the common baseline).
  2. Install: npm i -g @tansr/cli, npm install @tansr/sdk, npm install @tansr/serve, or the Maven / SwiftPM / independently published HAR coordinates.
  3. Credentials: which credential layer this form needs and where to get it.
  4. First session: the shortest runnable code.
  5. See the events: everything the agent produces is an event stream (msg.text.delta, tool.completed, …); this step lets you see it with your own eyes.
  6. Next steps: pointers to the in-depth guides.

Runtime requirements at a glance

Section titled “Runtime requirements at a glance”
Form Minimum
CLI The npm package needs Node.js ≥ 22.19 on Windows / macOS / Linux; the single-file executable (SEA) bundles its own runtime and is currently offered for Linux x64 / arm64 only
@tansr/sdk Node.js ≥ 22.19; Electron ≥ 39; ESM only; TypeScript target ≥ ES2022
@tansr/serve Node.js ≥ 22.19; the only third-party runtime dependency is zod
Android SDK minSdk 26; Kotlin coroutines + kotlinx.serialization + OkHttp
iOS SDK iOS 16+ / macOS 13+; SwiftPM
HarmonyOS SDK HarmonyOS 6.0 / API 20; Stage model; independently published HAR @tansr/harmony 0.2.0 (2026-10-10, not on OHPM yet)
Section titled “Once it runs, what to read next”
You care about Where to go
How sessions persist and how to recover after a disconnect Checkpoints and resume (SDK) · v2 protocol and webhooks (session service)
What capabilities the platform grants my app and how to toggle them in the console Platform assembly and the bundle
What an error code means and whether it is retryable Errors and retries · Error codes
How to deploy the backend, shut it down gracefully, shard across replicas Deployment and authentication
I want to call the session service’s HTTP surface (/api) directly, or write my own client Unified API (/api)
I want a coding assistant to build a running product from my description (@tansr/skill 0.1.6) Build a product with a coding assistant
Why the forms are split this way, and what the two steps and the roadmap mean Technical stance
Which parts of the SDK 2.0 extension entry points (archive host, cache host, unified API) are officially released SDK 2.0 extension entry points
How long sessions are kept and when they are reclaimed Retention and governance
Where the CLI config files live and how to read tansr doctor Settings and doctor
Where data lives, how to rotate keys, where traffic goes Security and privacy

If something goes wrong

Section titled “If something goes wrong”