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

# Synchronization

> How formae keeps its recorded state current when a resource changes outside of formae.

formae periodically checks the resources it already knows about against the cloud, so its state never goes stale, no matter who else touches your infrastructure.

## How synchronization works

Synchronization is enabled by default (every 5 minutes). On each run, formae reads the current state of every resource it knows about, managed and unmanaged alike, and compares it against what's recorded. If something changed outside formae, through the cloud console, another IaC tool, or a script, formae updates its own state to match immediately.

This does not touch your forma code or your cloud resources; formae just stops being stale. What happens on your next `apply` depends on the mode: [soft reconcile](/documentation/concepts/apply-modes#hard-vs-soft-reconcile) (the default) rejects the apply so you can review the drift, and `--force` (hard reconcile) overwrites it with your declared state. See [Apply modes](/documentation/concepts/apply-modes#hard-vs-soft-reconcile) for the full mechanism.

Synchronization is what lets you:

* Use formae alongside other tools without conflicts
* Make emergency changes through the cloud console when you need to
* Collaborate with teammates using different workflows
* Always have an accurate view of your infrastructure, regardless of how it was last touched

## Drift on cloud-defaulted properties

Some properties are filled in by the cloud when your forma does not declare them: a bucket's default encryption, a key's rotation setting, an engine version the service picks for you. Leaving such a property out of your forma can be a deliberate choice to rely on that default, so formae defends the default it observed when it created or last updated the resource the same way it defends a value you declared.

What happens to an out-of-band change on such a property depends on whether formae's own write produced the value that moved:

* **The value comes from formae's write.** When formae creates or updates a resource, it records what the cloud returned, including the defaults filled into properties your forma omits. A later out-of-band change to one of those values is ordinary drift: a soft reconcile (and a simulate) is rejected showing the change, and a forced reconcile reverts the property to the recorded value. To accept the new value instead, declare the property in your forma.
* **The value appeared on its own.** Properties the cloud or another system populates after formae's write, such as targets another service registers into a load balancer at runtime, are not treated as drift. They stay visible in `formae drift`, but they never reject an apply and `--force` never reverts them.

## Configuration

Synchronization is on by default. Tune the interval, or turn it off, in your [agent configuration](/documentation/reference/configuration#synchronization):

```pkl theme={"languages":{"custom":["/languages/pkl.json"]}}
agent {
  synchronization {
    enabled = true
    interval = 5.min  // How often to check for changes
  }
}
```

## Use cases

* **Emergency fixes.** Make a quick change through the cloud console during an incident. formae picks it up on the next sync, so your recorded state stays current even if your forma code hasn't changed yet.
* **Multi-tool environments.** If your team uses more than one tool to manage infrastructure, synchronization keeps formae's view accurate regardless of what made the change.
* **Gradual adoption.** Keep using your existing tools while formae tracks everything in the background, building a complete, current view of your infrastructure as you migrate.

<Tip>
  Synchronization works hand in hand with [discovery](/documentation/concepts/discovery). Discovery finds resources formae doesn't know about yet; synchronization keeps everything formae already knows about current.
</Tip>

## See also

* [Discovery](/documentation/concepts/discovery): how formae finds resources it doesn't manage yet.
* [Apply modes](/documentation/concepts/apply-modes): soft vs. hard reconcile, and how out-of-band changes affect an apply.