Quickstart - Synheart Documentation

This guide takes you from a fresh machine to a working Synheart integration. Pick the track that matches what you’re building.

Pick a track

Track A if you want a single, fused human-state signal (focus, emotion, capacity, recovery, strain, sleep) — typically because you’re building a wellness, productivity, or coaching app that already pulls data from a wearable and wants higher-level inference on top. Track B if you only need one channel of data — wearable readings, behavior events, or session frames — and want to wire it into your own pipeline. No CLI, no runtime, no platform account.

Track A — Synheart Core (HSI)

Multimodal human-state inference on-device. Requires CLI, platform account, and the runtime.

Track B — Standalone module

Just synheart_wear, synheart_behavior, or synheart_session. No CLI required.

Track A

Synheart Core (HSI). Use this track when you want fused human-state output (focus, emotion, capacity, recovery, strain, sleep) from biosignals + behavior + phone context.

1. Install the CLI

curl -fsSL https://synheart.sh/install | bash

Windows (PowerShell):

iwr -useb https://synheart.sh/install.ps1 | iex

Verify:

synheart version

Full install guide →

2. Create a platform account and register your app

Sign up at platform.synheart.ai (email + password, or Google, Apple, or GitHub). Signup is self-serve and starts on the free tier. Then create a project, add your app under Apps → Add App, and fill in App settings → SDK attestation: your bundle ID plus the Google project ID and Play Integrity decoder credential (Android) or Apple Developer Team ID (iOS). Turn on Allow development builds while you test on emulators, simulators, or debug builds. Note two values from the app page: the platform app_id (for example app_focus_and_kB8mPx) and your organization’s org_id. Both are in the Download App Credentials (.json) file.

Mobile apps don’t use API keys. The SDK registers a hardware-backed device identity, attested by Play Integrity or App Attest, and signs every request with it. Never ship an API key or signing secret in an app bundle.

Account setup → · Apps → · App attestation →

3. Authenticate the CLI

synheart login

Follow the device-flow prompt to sign in. Confirm:

synheart whoami

Authentication details →

4. Install the runtime

From your project root:

synheart install runtime --version 0.46.0

This downloads the native HSI engine and writes synheart.lock. Commit the lockfile so teammates and CI can run synheart sync. Run synheart doctor to check the installed runtime against your SDK. Runtime install guide →

5. Initialize Synheart Core

Flutter / Dart

# pubspec.yaml
dependencies:
  synheart_core: ^0.23.0

import 'package:flutter/foundation.dart';
import 'package:synheart_core/synheart_core.dart';

await Synheart.initialize(
  config: SynheartConfig(
    appId: 'app_focus_and_kB8mPx', // platform app_id
    subjectId: 'anon_user_123',
    wearConfig: const WearConfig(),
    deviceAuthConfig: const DeviceAuthConfig(
      authBaseUrl: 'https://api.synheart.ai',
      packageName: 'com.example.app', // your bundle ID / package name
      allowUnattestedDevRegistration: kDebugMode, // emulators and debug builds only
    ),
    cloudConfig: CloudConfig(
      subjectId: 'anon_user_123',
      instanceId: 'stable-installation-uuid',
      orgId: 'org_focus_kB8mPx',
    ),
  ),
);

Synheart.onHSIUpdate.listen((hsiJson) {
  print('HSI: $hsiJson');
});

// Granting cloudUpload is what triggers device registration and attestation.
await Synheart.grantConsent(
  biosignals: true,
  behavior: false,
  phoneContext: false,
  cloudUpload: true,
);
await Synheart.startSession();

Android (Kotlin)

// build.gradle.kts
dependencies {
    implementation("ai.synheart:synheart-core:0.8.0")
}

import ai.synheart.core.Synheart
import ai.synheart.core.config.CloudConfig
import ai.synheart.core.config.DeviceAuthConfig
import ai.synheart.core.config.SynheartConfig
import ai.synheart.core.config.WearConfig
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch

// The Synheart calls are suspend functions; run them from a coroutine.
lifecycleScope.launch {
    Synheart.initialize(
        context = context,
        config = SynheartConfig(
            appId = "app_focus_and_kB8mPx", // platform app_id
            subjectId = "anon_user_123",
            wearConfig = WearConfig(),
            deviceAuthConfig = DeviceAuthConfig(
                authBaseUrl = "https://api.synheart.ai",
                packageName = "com.example.app", // your applicationId
                allowUnattestedDevRegistration = BuildConfig.DEBUG, // emulators and debug builds only
            ),
            cloudConfig = CloudConfig(
                subjectId = "anon_user_123",
                orgId = "org_focus_kB8mPx",
                instanceId = "stable-installation-uuid",
            ),
        ),
    )

    Synheart.grantConsent("biosignals")
    // Granting cloudUpload is what triggers device registration and attestation.
    Synheart.grantConsent("cloudUpload")
    Synheart.startSession()

    Synheart.onHSIUpdate.collect { hsiJson ->
        println("HSI: $hsiJson")
    }
}

Kotlin SDK 0.7.0 and earlier also need allowUnsignedCapabilities = true next to deviceAuthConfig; without it initialize() throws. 0.7.1 fixed this.

iOS (Swift)

// Package.swift
.package(url: "https://github.com/synheart-ai/synheart-core-swift.git", from: "0.7.1")

import SynheartCore
import Combine

var cancellables = Set<AnyCancellable>()

let subjectId = "anon_user_123"

#if DEBUG
let isDevBuild = true  // simulators can't run App Attest
#else
let isDevBuild = false
#endif

let config = SynheartConfig(
    appId: "app_focus_and_kB8mPx", // platform app_id
    subjectId: subjectId,
    cloudConfig: CloudConfig(
        subjectId: subjectId,
        instanceId: "stable-installation-uuid",
        orgId: "org_focus_kB8mPx"
    ),
    deviceAuthConfig: DeviceAuthConfig(
        authBaseUrl: "https://api.synheart.ai",
        packageName: "com.example.app", // your bundle ID
        allowUnattestedDevRegistration: isDevBuild // simulators and debug builds only
    )
)

try await Synheart.initialize(config: config, userId: subjectId)

Synheart.onHSIUpdate
    .sink { hsiJson in print("HSI: \(hsiJson)") }
    .store(in: &cancellables)

try await Synheart.grantConsent("biosignals")
// Granting cloudUpload is what triggers device registration and attestation.
try await Synheart.grantConsent("cloudUpload")
try await Synheart.startSession()

appId is the platform-issued app_id. packageName is your installed bundle ID, which Play Integrity and App Attest check. Swapping them fails attestation. Cloud upload stays off until cloudConfig.orgId is set and the user grants cloudUpload consent.

To run local-only first, with nothing leaving the device, drop deviceAuthConfig and cloudConfig and set allowUnsignedCapabilities: true instead. Use that for development only.

initialize throws when the installed runtime doesn’t match the SDK (current SDKs need runtime 0.45.0 or later and recommend 0.46.0): SynheartRuntimeException on Flutter and Kotlin, SynheartRuntimeError on Swift. The error’s installCommand is the exact command that fixes it. On Flutter and Kotlin a missing runtime doesn’t throw: the SDK starts without HSI and Synheart.runtimeError says why. On Swift, a runtime that isn’t linked throws SynheartError.runtimeIncompatible.

6. Test locally with mock data (optional)

synheart init         # optional: write .synheart/config.yaml for this project
synheart local        # mock platform server (consent + ingest APIs)
synheart mock start   # mock wearable stream on ws://127.0.0.1:8787/hsi

CLI reference →

Track B

Standalone module. If you only need a single signal channel and don’t need fused HSI output, install just that SDK. No CLI, account, or runtime needed.

Synheart Wear

Biosignals from Apple Watch, WHOOP, Garmin, Fitbit, BLE HRMs.

Synheart Behavior

Tap, scroll, type, and motion patterns — content-free.

Synheart Session

Time-bounded sessions with HR + behavioral metrics on-device.

Quick example — synheart_wear in Flutter:

dependencies:
  synheart_wear: ^0.6.2

import 'package:synheart_wear/synheart_wear.dart';

final synheart = SynheartWear(
  config: SynheartWearConfig.withAdapters({DeviceAdapter.platformHealth}),
);
await synheart.initialize();

synheart.streamHR(interval: const Duration(seconds: 5)).listen((m) {
  print('HR: ${m.getMetric(MetricType.hr)}');
});

How it fits together

CLI authenticates you, manages the runtime artifact, and runs local mocks for development.
Runtime is the native on-device engine that computes HSI. The Core SDK loads it at startup.
Core SDK (Flutter / Kotlin / Swift) coordinates signal collection, drives the runtime, and exposes reactive streams.
Modules (synheart_wear, synheart_behavior, synheart_session) can be used standalone or composed under Core.

Privacy posture

On-device

Inference runs locally — no biosignal content leaves the device.

Consent-gated

Cloud uploads require explicit user consent and capability tokens.

Content-free

No text, audio, screen content, or PII is ever captured.

Synheart Core

Architecture, HSI/HSV spec, capabilities, consent.

CLI reference

Mock streams, local platform, install, sync, receiver.

Modules

Wear, Behavior, Session details.

Troubleshooting

Common issues and fixes.

Pick a track

Track A — Synheart Core (HSI)

Track B — Standalone module

Track A

1. Install the CLI

2. Create a platform account and register your app

3. Authenticate the CLI

4. Install the runtime

5. Initialize Synheart Core

6. Test locally with mock data (optional)

Track B

Synheart Wear

Synheart Behavior

Synheart Session

How it fits together

Privacy posture

On-device

Consent-gated

Content-free

Next

Synheart Core

CLI reference

Modules

Troubleshooting