> For the complete documentation index, see [llms.txt](https://sync.objectbox.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sync.objectbox.io/mesh-sync.md).

# Mesh Sync

Mesh Sync lets ObjectBox Sync clients synchronize directly with nearby peers (peer-to-peer, P2P). It is intended for offline-first apps where devices may meet locally and exchange changes. Typically, Mesh Sync is complementing the regular Sync Server by providing local sync while no Internet is available.

{% hint style="info" %}
ObjectBox Mesh Sync is currently available as a **preview for Android** (Java/Kotlin and Flutter/Dart). More platforms will follow; let us know if you are interested. Please also note that the APIs are still subject to change until the final release. For a list of current limitations, see [Current Limitations](#current-limitations).
{% endhint %}

## Overview

<figure><img src="/files/sqTPUePziIXdcUmwJNwu" alt="ObjectBox Mesh Sync Overview"><figcaption><p>Figure 1: ObjectBox Mesh Sync Overview</p></figcaption></figure>

Mesh Sync forms a local mesh network of devices to synchronize data between them. It can use different technology stacks, such as Bluetooth (classic and BLE), Wi-Fi (LAN and Wi-Fi Aware) and others. This allows data to move across devices even if not every device is directly connected to every other device.

Mesh Sync starts and stops together with the `SyncClient` and can coexist with regular Sync Server synchronization.

## Code: Initializing Mesh Sync

These minimal examples create the normal `SyncClient`, attach a mesh configuration and start syncing. Use the same mesh identifier on all apps/devices that should join the same mesh.

{% tabs %}
{% tab title="Java" %}

```java
import io.objectbox.android.sync.MeshConfig;
import io.objectbox.sync.Sync;
import io.objectbox.sync.SyncClient;
import io.objectbox.sync.SyncCredentials;

SyncClient syncClient = Sync.client(boxStore)
        .url("ws://sync.example.com:9999")
        .credentials(SyncCredentials.none())
        .build();

MeshConfig.builder(context)
        .serviceId("io.objectbox.example.sync.tasks")
        .build()
        .applyTo(syncClient);

syncClient.start();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
import io.objectbox.android.sync.MeshConfig
import io.objectbox.sync.Sync
import io.objectbox.sync.SyncCredentials

val syncClient = Sync.client(boxStore)
        .url("ws://sync.example.com:9999")
        .credentials(SyncCredentials.none())
        .build()

MeshConfig.builder(context)
    .serviceId("io.objectbox.example.sync.tasks")
    .build()
    .applyTo(syncClient)

syncClient.start()
```

{% endtab %}

{% tab title="Dart/Flutter" %}

```dart
import 'package:objectbox/objectbox.dart';
import 'package:objectbox_sync_flutter_libs/objectbox_sync_flutter_libs.dart'
    show createMeshConfig;

final mesh = await createMeshConfig('io.objectbox.example.sync.tasks');

final syncClient = SyncClient(
  store,
  ['ws://sync.example.com:9999'],
  [SyncCredentials.none()],
  mesh: mesh,
);

syncClient.start();
```

{% endtab %}

{% tab title="C++" %}

```cpp
#include "objectbox-sync.hpp"

obx::MeshOptions meshOptions("io.objectbox.example.sync.tasks");

// Provided by a platform SDK or custom transport integration.
meshOptions.registerNetwork(networkSharedPtr);

std::shared_ptr<obx::SyncClient> syncClient = obx::Sync::client(store)
    .url("ws://sync.example.com:9999")
    .credentials(obx::SyncCredentials::none())
    .mesh(std::move(meshOptions))
    .build();

syncClient->start();
```

Note: The C and C++ APIs expose the underlying mesh options, but a platform transport must be registered before creating the Sync client. Do not use `obx_mesh_opt_network_internal()` directly unless your platform SDK or integration provides the required transport handle.
{% endtab %}

{% tab title="C" %}

```c
#include "objectbox-sync.h"

OBX_sync_options* sync_opt = obx_sync_opt(store);
obx_sync_opt_add_url(sync_opt, "ws://sync.example.com:9999");

OBX_mesh_options* mesh_opt = obx_mesh_opt("io.objectbox.example.sync.tasks");

// Provided by a platform SDK or custom transport integration.
obx_mesh_opt_network_internal(mesh_opt, network_shared_ptr);

// obx_sync_opt_mesh() consumes mesh_opt, including when an error occurs.
obx_sync_opt_mesh(sync_opt, mesh_opt);

OBX_sync* sync_client = obx_sync_create(sync_opt);
obx_sync_credentials(sync_client, OBXSyncCredentialsType_NONE, NULL, 0);
obx_sync_start(sync_client);
```

Note: The C and C++ APIs expose the underlying mesh options, but a platform transport must be registered before creating the Sync client. Do not use `obx_mesh_opt_network_internal()` directly unless your platform SDK or integration provides the required transport handle.
{% endtab %}
{% endtabs %}

## Setup

Keep the regular ObjectBox Sync plugin and setup from [Sync Client](/sync-client.md#objectbox-sync-enabled-library).

For Android, Mesh Sync requires the Sync-enabled ObjectBox Android runtime and Google Nearby Connections.

{% tabs %}
{% tab title="Android Kotlin DSL" %}
You still use the latest official ObjectBox version, and add the preview runtime dependency explicitly. The direct `objectbox-sync-android-db` dependency is an override for the transitive native runtime while Mesh Sync is in preview.

```kotlin
dependencies {
    implementation("io.objectbox:objectbox-sync-android-db:6.0.0-preview1")
    implementation("com.google.android.gms:play-services-nearby:19.3.0")
}
```

{% endtab %}

{% tab title="Android Groovy" %}
You still use the latest official ObjectBox version, and add the preview runtime dependency explicitly. The direct `objectbox-sync-android-db` dependency is an override for the transitive native runtime while Mesh Sync is in preview.

```groovy
dependencies {
    implementation "io.objectbox:objectbox-sync-android-db:6.0.0-preview1"
    implementation "com.google.android.gms:play-services-nearby:19.3.0"
}
```

{% endtab %}

{% tab title="Dart/Flutter" %}
Use the preview ObjectBox Dart package that contains Mesh Sync support.

```yaml
dependencies:
  objectbox: ^6.0.0-preview.1
```

{% endtab %}
{% endtabs %}

## Permissions

Mesh Sync may use Bluetooth, Wi-Fi and location-related Android permissions for discovery and connections.

{% tabs %}
{% tab title="Android XML" %}
Declare the required permissions in `AndroidManifest.xml`.

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Permissions required by Object Mesh Sync -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation" />
    <uses-permission
        android:name="android.permission.NEARBY_WIFI_DEVICES"
        android:usesPermissionFlags="neverForLocation" />
</manifest>
```

{% endtab %}
{% endtabs %}

### Runtime Permissions

Request all runtime permissions before starting Mesh Sync. On modern Android versions this typically includes nearby devices, Bluetooth scan/connect/advertise and location permissions. Location services may also need to be enabled on the device for discovery to work reliably.

{% tabs %}
{% tab title="Android (Kotlin/Java)" %}
Use the standard procedure to [request runtime permissions](https://developer.android.com/training/permissions/requesting) within the app.
{% endtab %}

{% tab title="Dart/Flutter" %}
In Dart, `createMeshConfig()` requests the required runtime permissions from the user via the system UI (you still need to define them in `AndroidManifest.xml`). Alternatively, you can also implement your own permission request logic, and pass `false` to the `requestPermissions` parameter to prevent requesting runtime permissions. Note that `createMeshConfig()` will only request runtime permissions if they are not already granted.
{% endtab %}
{% endtabs %}

## Configuration

The mesh identifier controls which peers can discover each other. Peers with different identifiers ignore each other. Use different identifiers to isolate sync groups.

| Option                            | Default  | Description                                                                       |
| --------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `meshId`                          | Required | Mesh network identifier.                                                          |
| `maxConnectionCount`              | `3`      | Maximum number of simultaneous peer connections.                                  |
| `backoffMillis`                   | `10000`  | Delay before retrying a failed connection.                                        |
| `evictionBackoffMillis`           | `30000`  | Delay between peer evictions when a full peer makes room for a newcomer.          |
| `randomSeed`                      | `0`      | Random seed; `0` uses the current time.                                           |
| `requestTimeoutMillis`            | `5000`   | Timeout for requesting a missing sync log from a peer before trying another peer. |
| `advertisingDelayMillis`          | `2000`   | Delay before advertising starts after Mesh Sync starts.                           |
| `connectDelayMillis`              | `1000`   | Minimum delay between outgoing connection attempts.                               |
| `initialDiscoveryDurationSeconds` | `30`     | Duration of the first discovery phase; `0` means it does not stop by time.        |
| `discoveryDurationSeconds`        | `15`     | Duration of later discovery phases; `0` means they do not stop by time.           |
| `discoveryPauseSeconds`           | `45`     | Pause between discovery phases.                                                   |
| `discoveryPauseJitterSeconds`     | `15`     | Random positive or negative jitter applied to the discovery pause.                |
| `txLogBatchSizeKb`                | `100`    | Soft payload size cap for batching sync logs into a single transfer.              |
| `txLogBatchMaxCount`              | `1000`   | Maximum number of sync logs to batch into one transfer.                           |

The default `maxConnectionCount` of `3` is a good starting point for most meshes. A value of `4` may improve fault tolerance, but it increases radio activity. Values above `4` are usually not recommended. A value of `1` creates pairs and is not a real mesh topology.

Set configuration options using the API for your language. The following examples show how to configure a mesh and set `maxConnectionCount` to `4` where the current API exposes it.

{% tabs %}
{% tab title="Java" %}
The Java preview API currently exposes Android Nearby options such as `serviceId`, but not `maxConnectionCount`.

```java
MeshConfig.builder(context)
        .serviceId("io.objectbox.example.sync.tasks")
        .build()
        .applyTo(syncClient);
```

{% endtab %}

{% tab title="Kotlin" %}
The Kotlin preview API currently exposes Android Nearby options such as `serviceId`, but not `maxConnectionCount`.

```kotlin
MeshConfig.builder(context)
    .serviceId("io.objectbox.example.sync.tasks")
    .build()
    .applyTo(syncClient)
```

{% endtab %}

{% tab title="Dart/Flutter" %}

```dart
final mesh = createMeshConfig(
  'io.objectbox.example.sync.tasks',
  maxConnectionCount: 4,
);
```

{% endtab %}

{% tab title="C++" %}

```cpp
obx::MeshOptions meshOptions("io.objectbox.example.sync.tasks");
meshOptions.maxConnectionCount(4);
```

{% endtab %}

{% tab title="C" %}

```c
OBX_mesh_options* mesh_opt = obx_mesh_opt("io.objectbox.example.sync.tasks");
obx_mesh_opt_max_connection_count(mesh_opt, 4);
```

{% endtab %}
{% endtabs %}

If several devices start at the same time, give discovery and connection setup a little time. Mesh Sync intentionally staggers advertising and outgoing connection attempts to reduce radio contention.

## Diagnostics

The running mesh can report its state and connected peer count. Important states are `Created`, `Discovering`, `FullyConnected`, `Stopped` and `Dead`. Useful counters include discovered peers, connected peers, failed connection attempts, sent and received messages, received sync logs and applied sync logs.

{% tabs %}
{% tab title="Dart/Flutter" %}

```dart
final mesh = syncClient.mesh;
if (mesh != null) {
  print(mesh.stateString());
  print(mesh.connectedPeerCount());
  print(mesh.stats(MeshStats.txLogsApplied));
}
```

{% endtab %}

{% tab title="C++" %}

```cpp
obx::Mesh mesh = syncClient->mesh();
if (mesh.isAttached()) {
    std::cout << mesh.stateString() << std::endl;
    std::cout << mesh.connectedPeerCount() << std::endl;
    std::cout << mesh.statsU64(OBXMeshStats_txLogsApplied) << std::endl;
}
```

{% endtab %}

{% tab title="C" %}

```c
OBX_mesh* mesh = obx_sync_mesh(sync_client);
if (mesh) {
    printf("%s\n", obx_mesh_state_string(mesh));
    printf("%zu\n", obx_mesh_connected_peer_count(mesh));

    uint64_t applied = 0;
    obx_mesh_stats_u64(mesh, OBXMeshStats_txLogsApplied, &applied);
    printf("Applied sync logs: %llu\n", (unsigned long long) applied);
}
```

{% endtab %}
{% endtabs %}

## Current Limitations

Mesh Sync is currently in public preview. Until the final release, we'll finalize the API and plan to address the following limitations.

* Only works on Android (Mesh Sync has a network abstraction layer that is currently only implemented for Android)
* Transactions are limited to \~ 1000 KB (compressed); larger ones (e.g., containing larger phtotos/videos) are ignored.
* Mesh Sync data is kept in memory only; it's not persisted to disk.
* No expiration of data; there will be a setting to limit the time and/or size of the data that is synced to the mesh.
* No optimized interaction with the Sync Server yet; e.g.:
  * Only the peer of the original edit syncs that data to the server. In the future, any peer having the data can sync it to the server.
  * Changes from the server are not synced to the mesh.
* Java/Kotlin API is very limited
* Advertising is only initiated once on startup; if that fails, e.g. due to missing permissions, Mesh Sync will not retry.
* TBD: Peer authentication; currently there's no auth between peers other than the mesh ID.
* TBD: permission handling details
* TBD: the mesh ID (required at construction time) is the only mechanism to form sync groups.
* TBD: clarify if Nearby dependency shall already be included by the lib or needs to be added by the user.

## Related Pages

* [Sync Client](/sync-client.md)
* [Troubleshooting Sync](/troubleshooting-sync.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sync.objectbox.io/mesh-sync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.