> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsentinel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote sync

> Upload local ledger entries to the Agent Sentinel Platform in the background.

Remote sync batches local ledger entries and uploads them to the platform ingest endpoint:

```text theme={null}
POST /api/v1/ingest/
```

## Install

```bash theme={null}
pip install "agentsentinel-sdk[remote]"
```

## Enable sync (recommended)

```python theme={null}
from agent_sentinel import enable_remote_sync, flush_and_stop

sync = enable_remote_sync(
    platform_url="https://platform.agentsentinel.dev",
    api_token="as_your_api_key_here",
    agent_id="my-agent",     # optional; tags every batched entry with this agent
    run_id=None,             # optional; auto-generated if None
    flush_interval=10.0,     # seconds between uploads
    auto_start=True,         # set False to defer the background thread until you call .start()
)

# If you want to query the run in the platform API:
print(sync.config.run_id)

# ... run your agent ...

flush_and_stop()
```

### Parameters

| Parameter        | Default        | Purpose                                                                                                                         |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `platform_url`   | required       | Platform base URL (e.g. `https://api.agentsentinel.dev`)                                                                        |
| `api_token`      | required       | JWT or API key                                                                                                                  |
| `agent_id`       | `None`         | Tags every batched entry with this agent identifier                                                                             |
| `run_id`         | auto-generated | Logical run grouping; pass an explicit ID for deterministic correlation                                                         |
| `flush_interval` | `10.0`         | Seconds between batched uploads                                                                                                 |
| `auto_start`     | `True`         | If `False`, the returned `BackgroundSync` instance is created but the worker thread doesn't start until you call `sync.start()` |

## Authentication

The SDK sends:

```text theme={null}
Authorization: Bearer <api_token>
```

The platform ingest route accepts:

* JWT tokens (user sessions)
* API keys (recommended for agents)

## Operational behavior

* Uploads are retried with exponential backoff (network/server errors).
* Auth failures (401) are not retried.
* If the platform is down, entries remain local and your agent continues.