tentacle-sdk

TypeScript SDK for the Tentacle API.

Installation

npm install tentacle-sdk

Usage

Tentacle runs as a local desktop app, so the SDK connects to the local sidecar over loopback by default. No access token is required - just have the Tentacle desktop app running on the same machine.

import { TentacleClient } from "tentacle-sdk"

const client = new TentacleClient()

// Request/response API
const { collections } = await client.api.viewerProperty.listCollections()
const events = await client.api.stream.getLatestEvents({ take: 20 })

// Realtime events over SSE
client.realtime.onEvent((event) => {
  console.log(event.kind)
})
client.realtime.connect()

To target a non-default address (for example a custom sidecar port), pass baseUrl:

const client = new TentacleClient({ baseUrl: "http://127.0.0.1:51234" })

Finding the sidecar port

By default the desktop app binds its sidecar to the fixed port 47821, which is also the SDK's default - so new TentacleClient() connects with no configuration. You only need to look the port up if you changed it in Settings → System, or if 47821 was already in use and the app fell back to an OS-assigned port.

In those cases, read the discovery file the sidecar writes on startup. It sits next to the app's database in the OS app-data dir (on Windows, %APPDATA%\live.tentacle.desktop\sidecar.json) and looks like:

{
  "port": 51234,
  "baseUrl": "http://127.0.0.1:51234"
}

Pass its baseUrl straight to the client:

import { readFileSync } from "fs"

const { baseUrl } = JSON.parse(readFileSync(sidecarJsonPath, "utf8"))
const client = new TentacleClient({ baseUrl })

If you prefer a stable address, set a fixed port in Settings → System and pass it as baseUrl directly.

Migration to 0.5.0

0.5.0 adapts the SDK to the local desktop version of Tentacle:

• Removed the required accessToken option. The SDK now talks to the local Tentacle sidecar on loopback, which does not require token authentication. Delete any accessToken you were passing to new TentacleClient(...).
• baseUrl now defaults to the local sidecar (http://127.0.0.1:47821) instead of a hosted URL. baseUrl remains optional and overridable.
• The Settings → Access Tokens screen no longer exists in the app; there is nothing to generate or paste.