Sync Agent
How the SikkerKey agent manages database credentials automatically.
The sync agent is a process that runs next to your database and applies credential rotations automatically. When SikkerKey rotates a managed secret's password, the agent connects to your database and executes the appropriate command (e.g. ALTER ROLE ... WITH PASSWORD for PostgreSQL) so the new credential is live everywhere.
Your database does not need to be exposed to the internet. The agent runs locally on the same network as your database and communicates with SikkerKey over HTTPS using the same Ed25519 machine authentication as the SDK and CLI.
How It Works
Managed secrets use a two-phase rotation model:
- SikkerKey generates a new password but does not update the live secret. The new value is stored as a pending rotation.
- The agent detects the pending rotation on its next poll (every 10 seconds).
- The agent applies the new password to the database using admin credentials.
- The agent verifies the new password works by connecting as the managed user with the new credentials.
- On success, the agent confirms back to SikkerKey. SikkerKey promotes the pending value to the live secret, bumps the version, and records it in the audit log.
- On failure, the agent rejects the rotation. SikkerKey clears the pending value and records the error. The live secret stays at the old (working) password. No split credentials.
Machines reading the secret via SDK or CLI always get the currently working password. The value only updates after the database is confirmed to have the new one.
Supported Providers
| Provider | Credential Command |
|---|---|
| PostgreSQL | CREATE ROLE / ALTER ROLE ... WITH PASSWORD |
| MySQL | CREATE USER / ALTER USER ... IDENTIFIED BY |
| Redis | ACL SETUSER (Redis 6+) or CONFIG SET requirepass (legacy) |
| MongoDB | createUser / updateUser |
Running the Agent
Install as a service (recommended)
sudo sikkerkey agent install --secret sk_abc123 --now
Generates and installs a system service:
- Linux: systemd unit at
/etc/systemd/system/sikkerkey-agent-{id}.service - macOS: launchd plist at
~/Library/LaunchAgents/com.sikkerkey.agent.{id}.plist - Windows: NSSM service (preferred) or sc.exe
The service starts automatically on boot and restarts on failure with a 10-second delay.
Run in the foreground
sikkerkey agent start --secret sk_abc123
Blocks until interrupted. Useful for testing and debugging.
Prerequisites
The machine running the agent must:
- Be bootstrapped with a SikkerKey identity (
sikkerkey connect+sikkerkey unlock) - Be approved in the dashboard
- Be added to the project containing the managed secret
- Have an explicit access grant to the managed secret
This is the same six-requirement access model as any other secret read. The agent is not a special case.
Agent Lock
Each managed secret is locked to a single agent machine. The first machine to fetch the sync config becomes the registered agent for that secret. If a different machine tries to run the agent for the same secret, it gets rejected with HTTP 409.
This prevents two agents from racing to apply the same rotation.
Polling and Heartbeats
The agent polls the sync config endpoint every 10 seconds and sends heartbeats every 30 seconds. The dashboard shows agent health in real time:
| Status | Meaning |
|---|---|
| No agent | No agent has connected yet |
| Healthy | Agent is running and heartbeating |
| Unhealthy | No heartbeat received for 90+ seconds |
| Error | Agent reported an error (e.g. database connection failed) |
If the agent is unhealthy, SikkerKey holds pending rotations. Rotations resume automatically when the agent recovers.
What Happens When Things Break
| Scenario | Behavior |
|---|---|
| Agent is down when rotation fires | Pending rotation is held. Secret stays at old password. Dashboard shows "Rotation pending." Agent applies it when it comes back. |
| Database is unreachable during apply | Agent rejects the rotation. SikkerKey clears pending state and logs the error. Old password still works everywhere. |
| Apply succeeds but verification fails | Agent attempts to rollback the database to the old password, then rejects. SikkerKey stays at the old value. |
| Agent crashes mid-apply | Next agent startup detects the pending rotation and retries. |
| Secret is deleted from dashboard | Agent gets 404 on next poll and exits cleanly. |
| Machine access is revoked | Agent gets 403 on next poll and exits cleanly. |
| Two agents for the same secret | Second agent is rejected with HTTP 409. |
| Rotation fails repeatedly | Dashboard shows "Rotation failed" with the error. Click "Retry rotation" to reset and try again on the next cycle. |
CLI Commands
See the Agent Commands page for the full command reference: start, install, configure, test, list, stop, remove.