Clock Drift
Long-running enclaves can drift away from the parent instance wall clock, which is enough to break real application flows.
Developers usually see this as intermittent JWT expiry problems, TLS certificate validation failures, or mismatched timestamp windows. Capsule includes host-assisted clock sync so application teams do not need to build and maintain time synchronization themselves.
Why You Should Care
Clock drift matters as soon as your application depends on absolute time instead of just elapsed time.
JWT and token validation starts failing
If the enclave clock drifts far enough, even correct tokens can look expired or not yet valid.
TLS and certificate checks become unreliable
Clock errors can make certificate validity windows look wrong and produce confusing transport failures.
The failure often looks unrelated to time
Because the app is otherwise healthy, teams often debug credentials, networking, or SDK logic before realizing the problem is clock drift.
What Capsule Does By Default
Capsule enables clock sync unless you explicitly disable it.
Capsule Shell starts a host-side time server
The host launches a VSOCK time service before the enclave is considered fully ready.
Capsule Runtime performs an initial sync
At startup, Capsule Runtime synchronizes the enclave wall clock before the application settles into normal runtime behavior.
Capsule Runtime keeps syncing periodically
If clock_sync is omitted, the default interval is 300 seconds. You can tighten the interval if your workload is especially time-sensitive.
Manifest Configuration
Most teams should keep the defaults and only change the interval if they have a specific reason.
# Omit the block entirely
# Or keep the default explicitly
clock_sync: {}clock_sync:
interval_secs: 60What clock sync does not solve
Clock sync improves operational correctness, but it does not create a new trusted time root. If the parent instance time is wrong, the enclave time will also be wrong.
- Keep clock sync enabled for JWT, TLS, and timestamped credential flows.
- Use monotonic time inside the application for elapsed-time measurement.
- If you disable clock sync, expect drift in long-lived enclaves and plan around it explicitly.
Next step: once clock handling is clear, move to Nitro Host Setup if you still need to prepare allocator memory or hugepages.