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”.

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 Android and iOS in 5 minutes
I am writing an iOS / macOS app, backend as above Swift package tansr-ios the “Same on iOS” section of the same article

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 SDKs are thin protocol clients that never hold any platform credential; the agent kernel runs inside the @tansr/serve you deploy.

The account model shared by all five paths

Section titled “The account model shared by all five 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 four form articles (Android and iOS share one) 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 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 (npm package) Node.js ≥ 22.19; Windows / macOS / Linux. The single-file executable bundles its own runtime and needs no Node
@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
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
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”