Software
Secret Server Agent
A single Go binary, standard library only, that connects a computer to your SecretServer account and delivers the secrets and services an admin assigned to that device.
What it is
| Capability | Behavior |
|---|---|
| Account login | OAuth2 browser approval or API-key enrollment |
| Device identity | Ed25519 proof of possession on every device request |
| Access assignments | Server-managed profiles with exact resource grants |
| Secret delivery | Private JSON files refreshed automatically |
| Signing | Requests signatures from an assigned server-side key; private keys are never downloaded |
| Database access | Requests credentials from an assigned database role on demand |
| Revocation | Enforced on the next request; a failed refresh clears delivered files |
After enrollment the agent keeps neither the API key nor the OAuth token. Only its own device key authenticates later requests.
Who it is for
- Operators who want servers to receive their credentials without storing a long-lived account API key on each host.
- Teams that need per-device revocation: disable one host without rotating a shared key.
- Build and release hosts that need to sign or resolve %%NAME%% variables with an identity scoped to exactly those resources.
How it works
- 1
Admin defines a profile
An account admin creates an access profile listing exact grants: a secret, a variable, a signing key or a database role. No wildcards.
- 2
Device generates a key
login creates an Ed25519 key pair and saves it to a private state directory before any network call.
- 3
Enrollment
The device enrolls with an admin API key file or through OAuth2 device approval in the browser, where the approving account member compares the key fingerprint.
- 4
Signed requests
Every later request is signed with the device key over the account, device, method, URI, time, nonce and body hash. The server checks revocation and replay on each one.
- 5
Delivery
run fetches assigned secrets and writes each as a private <alias>.json file, refreshed on a polling interval and removed on failure or shutdown.
Transport security is certificate-verified TLS 1.3 with redirects refused. The server accepts a signed request only once (nonces are stored) and only within 60 seconds of its timestamp.
Install
The repository is public under the MIT license. Install with Go 1.27.1 or newer:
go install github.com/afterdarksys/secretserver-agent/cmd/secretserver-agent@latest
Or build from a checkout:
git clone https://github.com/afterdarksys/secretserver-agent.git cd secretserver-agent go build -o bin/secretserver-agent ./cmd/secretserver-agent
Enroll
# Browser approval (OAuth2 device flow) bin/secretserver-agent login \ --server https://api.secretserver.io \ --account ACCOUNT_UUID --profile PROFILE_UUID --name web-01 # Unattended, with a 0600 file holding an admin API key bin/secretserver-agent login \ --server https://api.secretserver.io \ --account ACCOUNT_UUID --profile PROFILE_UUID --name web-01 \ --api-key-file /secure/enrollment-api-key
Browser approval needs an account member with the agents:approve permission. The device code expires after 10 minutes, and the enrollment token it yields is single-use and bound to that exact public key, name, account and profile. Creating or changing profiles needs admin:*.
Remove the bootstrap key file once enrollment succeeds. Revoking that key does not revoke devices it enrolled.
Use
bin/secretserver-agent status bin/secretserver-agent access --alias app-config bin/secretserver-agent render --json --input app.template.json > app.private.json bin/secretserver-agent run --output-dir /absolute/private/secrets --poll 30s
Run as a Linux service
useradd --system --no-create-home --shell /usr/sbin/nologin secretserver-agent install -m 0755 bin/secretserver-agent /usr/local/bin/secretserver-agent install -d -m 0700 -o secretserver-agent -g secretserver-agent /var/lib/secretserver-agent # enroll as the service user with --state-dir /var/lib/secretserver-agent, then: install -m 0644 deploy/secretserver-agent.service /etc/systemd/system/ systemctl daemon-reload systemctl enable --now secretserver-agent
There are no prebuilt downloads; go install or go build produces the binary. Building it does not start or install anything.
Platform support
| Platform | Status |
|---|---|
| Linux with systemd | Documented service target with a hardened sample unit |
| Other platforms Go supports | The binary builds from the same source; no service definition is shipped |
| Server | Needs the matching SecretServer API (migration 034_agents.sql) and HTTPS with TLS 1.3 |