Agent Commands
Run and manage sync agents for managed secrets.
The sikkerkey agent commands manage sync agents that apply credential rotations to external databases. Agents are used with managed secrets.
start
Run a sync agent in the foreground. Blocks until interrupted.
sikkerkey agent start --secret sk_abc123
The agent:
- Authenticates with SikkerKey using the machine's Ed25519 identity
- Fetches the sync configuration (provider, connection details, managed role)
- Tests the database connection and verifies admin privileges
- Reports its initial health status
- Polls for secret value changes every 10 seconds
- Applies new credentials to the database when rotations happen
- Sends heartbeats every 30 seconds
If no local config exists (from agent configure), the agent fetches the configuration from SikkerKey's server. This is the normal flow for managed secrets created from the dashboard.
install
Generate and install a system service that runs the agent automatically.
# Generate the service config (print without installing)
sikkerkey agent install --secret sk_abc123
# Generate and install immediately
sudo sikkerkey agent install --secret sk_abc123 --now
Supported service managers:
| OS | Service Manager |
|---|---|
| Linux | systemd (/etc/systemd/system/sikkerkey-agent-{id}.service) |
| macOS | launchd (~/Library/LaunchAgents/com.sikkerkey.agent.{id}.plist) |
| Windows | NSSM (preferred) or sc.exe |
Without --now, the command prints the service configuration and manual install instructions. With --now, it writes the config file and starts the service.
The service is configured to restart on failure with a 10-second delay.
configure
Manually configure the database connection for an agent. This creates a local config file that takes precedence over server-side configuration.
sikkerkey agent configure \
--secret sk_abc123 \
--provider postgresql \
--host localhost \
--port 5432 \
--database mydb \
--admin-user postgres \
--admin-pass s3cret
Use this for advanced setups where you want the agent config stored locally rather than fetched from SikkerKey.
Flags
| Flag | Description |
|---|---|
--secret <id> | Secret to sync (required) |
--provider <type> | Database type: postgresql, mysql, redis, mongodb |
--host <host> | Database hostname |
--port <port> | Database port (defaults to provider's standard port) |
--database <name> | Database name |
--admin-user <user> | Admin username with CREATEROLE or SUPERUSER privilege |
--admin-pass <pass> | Admin password |
--username-field <f> | Secret field containing the target username (default: username) |
--password-field <f> | Secret field containing the password to sync (default: password) |
--poll-interval <s> | Seconds between checks (default: 10) |
test
Test the database connection without starting the agent.
sikkerkey agent test --secret sk_abc123
Connects to the database using the configured credentials and verifies the admin user has sufficient privileges (CREATEROLE or SUPERUSER for PostgreSQL). Reports success or the specific error.
Requires a local config (from agent configure) for the specified secret.
list
Show agents running on this machine.
sikkerkey agent list
Displays a table with secret ID, provider, status (running/stopped), PID, and host for each configured agent.
stop
Stop a running agent.
sikkerkey agent stop --secret sk_abc123
remove
Remove the local agent config for a secret.
sikkerkey agent remove --secret sk_abc123
This only removes the local configuration file. It does not affect the managed secret or its rotation schedule on the server.