Skip to main content
All Docs
FeaturesBlockManOSUpdated April 9, 2026

agentOS Sync Integration

agentOS Sync Integration

BlockManOS v1.0.99 introduces a native integration with agentOS (LetMC property CRM), enabling bi-directional synchronisation of properties, contacts, and ownership data between the two platforms. This eliminates manual double-keying when an agency uses agentOS as its primary CRM alongside BlockManOS for block management.

Overview

EntityDirection (current)Notes
Properties / UnitsPull (agentOS → BlockManOS)Creates or updates units
Contacts / OwnersPull (agentOS → BlockManOS)Creates or updates owner records
Tenancies / OwnershipsPull (agentOS → BlockManOS)Links ownerships to units
Push syncFoundation in placeFull push support in a future release

Sync runs are processed asynchronously via an Inngest background function, keeping the dashboard responsive even during large data sets.

Prerequisites

  • An active agentOS (LetMC) account with API access enabled
  • Your agentOS API key (request from agentOS support or your agentOS account portal)
  • Your company short name — the identifier used in agentOS API URLs (e.g. mycompany)
  • Admin role in BlockManOS

Database migration required. Before using this feature, run the Drizzle migration to create the three agentOS schema tables.

Setting Up the Connection

  1. In the BlockManOS sidebar, open Integrations → agentOS Sync.
  2. Click Set Up Connection.
  3. Complete the configuration form:
FieldRequiredDescription
API KeyYesYour agentOS API key. Stored encrypted per-organisation; not exposed to the browser after saving.
Company Short NameYesYour agentOS company identifier (used in API URLs).
Branch IDNoOnly needed for multi-branch agentOS setups.
API Base URLNoDefaults to https://live-api.letmc.com. Change only if directed by agentOS support.
  1. Choose a Sync Direction:
    • Bidirectional (↔) — Data flows both ways (pull currently active; push foundation ready)
    • Pull (← agentOS) — Only import data from agentOS into BlockManOS
    • Push (→ agentOS) — Only export data from BlockManOS to agentOS
  2. Select which entity types to synchronise: Properties/Units, Contacts/Owners, Tenancies/Ownerships.
  3. Optionally enable Auto-Sync and set a sync interval (in minutes).
  4. Click Save Configuration.

Testing the Connection

After saving, the Connection Status panel appears. Click Test Connection to verify that BlockManOS can reach the agentOS API with your credentials. A green status indicator confirms a successful connection.

Running a Sync

Manual Sync

From the agentOS Sync dashboard page, use the sync controls to trigger an immediate run:

  • Full Sync — Processes all configured entity types in both directions
  • Pull — Imports from agentOS only
  • Push — Exports to agentOS only (push foundation in place; full push support coming in a future release)

Sync jobs run asynchronously. The page does not need to stay open — the job continues in the background.

Auto-Sync

Enable Auto-Sync in the configuration form and set an interval. BlockManOS will automatically dispatch a sync event on that schedule.

How the Sync Works

Admin triggers sync (manual or scheduled)
        │
        ▼
  Inngest event dispatched: agentos/sync.requested
        │
        ▼
  Background function picks up the event
        │
        ├─ Fetches contacts / landlords from agentOS API
        │   └─ Creates or updates Owner records in BlockManOS
        │
        ├─ Fetches properties from agentOS API
        │   └─ Creates or updates Unit records in BlockManOS
        │
        └─ Writes/updates entity mappings (agentOS ID ↔ BlockManOS ID)
                │
                ▼
          Sync log entry written with statistics and any errors

Entity mappings are stored in the agentos_sync_mappings table, linking each agentOS entity ID to the corresponding BlockManOS record. These mappings allow future incremental syncs to update existing records rather than creating duplicates.

Viewing Sync History

The Sync History table on the agentOS Sync page shows the last 10 sync runs, including:

  • Run status: pending, running, completed, completed_with_errors, failed
  • Start and end timestamps
  • Record counts (created, updated, skipped, errors) per entity type
  • Error details when a run encounters problems

Entity Mapping Summary

The Mappings panel shows a summary of currently mapped entities — how many properties, contacts, and tenancies are linked between the two systems.

Disconnecting agentOS

To remove the integration:

  1. Open Integrations → agentOS Sync.
  2. Click Delete Configuration (or Disconnect).
  3. Confirm the action.

This removes the API credentials and sync preferences. Existing entity mappings and sync logs are also cleaned up. Local BlockManOS records (owners, units) that were created via sync are not deleted.

Data & Security Notes

  • API keys are stored per-organisation in the BlockManOS database, not as shared environment variables. Each customer's agentOS credentials are isolated to their own organisation.
  • The API key is never returned to the browser after initial save. The getConfig endpoint omits the key field.
  • Authentication to the agentOS v3 API uses an API key passed as a query parameter, as required by the agentOS API scheme.
  • Sync runs are subject to concurrency and throttle controls to avoid overloading the agentOS API.

Troubleshooting

SymptomLikely causeResolution
"Test Connection" failsIncorrect API key or company short nameRe-enter credentials and save before testing
Sync completes with errorsSome agentOS records could not be mappedCheck the sync log detail view for per-record error messages
Sync never startsInngest function not reachableConfirm the Inngest route is accessible and the middleware passthrough rules are correct
Duplicate records appearingEntity mappings missingRun a Full Sync to rebuild the mapping table

Related