Configuring the Agent

This guide covers every setting the Keystash Agent understands — where the configuration lives, the full list of keys, the matching environment variables and command-line flags, and the rules that decide which value wins when a setting is provided in more than one place.

Configuration File Basics

The Keystash Agent reads its configuration from /etc/keystash/keystash.conf. The file is a flat INI file — one key=value per line, no sections.

Warning

The configuration file may contain your deployment secret, so the agent enforces 0600 permissions (owner read/write only, owned by root). The agent repairs the permissions if it can; if the file is left world- or group-readable and cannot be fixed, the agent refuses to start. Keep the file at 0600.

You will normally create this file once when first deploying a server — either by pasting the snippet shown in the Keystash app, or with the command-line configuration mode. After that, the agent manages most of it for you.

Required Configuration

# Your Keystash Account ID
account_id=XXXXXXXXXX

# Deployment Secret from your Keystash account
deployment_secret=XXXXXXXXXX

Note

All of the required settings can be found in the Keystash web interface under Server Management > Servers > Deploy to New Server.

Optional Configuration

# Server Group ID to place the server into a pre-defined group
server_group_id=XXXXXXXXXX

# Proxy configuration if required
proxy_url=https://proxy-server.example.com:8443

Full Key Reference

Key	Required	Description
account_id	required	Your 16-character Keystash Account ID.
deployment_secret	required	The 36-character Deployment Secret that authorises this server.
server_group_id	optional	A 16-character Server Group ID. Places the server straight into a pre-defined Server Group on first contact.
proxy_url	optional	An HTTP/HTTPS proxy URL the agent should route its traffic through.
keystash_server	optional	The Keystash endpoint hostname. Defaults to server-api.keystash.io. See Endpoint Configuration.
keystash_port	optional	The endpoint port. Defaults to 443. See Endpoint Configuration.
keystash_protocol	optional	The endpoint protocol. Defaults to https:. See Endpoint Configuration.

Note

The agent also writes machine-managed values such as server_id and cached_data into this file. These are maintained by the agent — do not hand-edit them.

Info

SSH Connection Logging is not configured here. It is controlled per Server Group from the Keystash app, not by any key in keystash.conf.

Endpoint Configuration

By default the agent talks to Keystash at server-api.keystash.io on port 443 over HTTPS. The three endpoint keys let you point the agent at a different target — for example a self-hosted or staging environment. The same binaries ship to every environment, so the target is chosen entirely at runtime.

Key	Default	Validation
keystash_server	server-api.keystash.io	Non-empty, no whitespace or /, 253 characters or fewer. Raw IP addresses and internal DNS names are allowed.
keystash_port	443	Integer between 1 and 65535.
keystash_protocol	https:	http or https, case-insensitive; the trailing colon is optional.

Environment Variables

Each endpoint key has a matching environment variable, which is handy for containers and orchestration where you would rather not write a file:

Environment variable	Equivalent key
KEYSTASH_SERVER	keystash_server
KEYSTASH_PORT	keystash_port
KEYSTASH_PROTOCOL	keystash_protocol
HTTPS_PROXY / HTTP_PROXY	proxy_url

Precedence

For the endpoint keys (keystash_server, keystash_port, keystash_protocol) the order of precedence is environment variable → configuration file → compiled-in default. In other words, an environment variable wins over the config file ("env-wins").

Note

This is the opposite of proxy_url, where the config file value wins over the environment variable. At startup the agent logs the endpoint it resolved and the source of each setting, so you can always confirm which value took effect.

Command Line Configuration

You can create or update the configuration file from the command line using the agent's config mode. This is the form the Keystash app gives you to copy and paste:

/opt/keystash/keystash-key-manager.bin --mode=config \
    --account_id=XXXXXXXXXX \
    --deployment_secret=XXXXXXXXXX \
    --server_group_id=XXXXXXXXXX \
    --proxy_url=https://proxy-server.example.com:8443

The endpoint settings can be supplied the same way when you need to override them:

/opt/keystash/keystash-key-manager.bin --mode=config \
    --account_id=XXXXXXXXXX \
    --deployment_secret=XXXXXXXXXX \
    --keystash_server=server-api.keystash.io \
    --keystash_port=443 \
    --keystash_protocol=https:

The --log-target Flag

The agent also accepts a --log-target flag that controls where its own diagnostic output is written:

• --log-target=stdout (default) - writes to standard output, which is captured by journald when the agent runs under systemd (journalctl -u keystash).
• --log-target=syslog - writes to an explicit syslog LOG_DAEMON sink instead.

Note

--log-target controls the agent's own diagnostic logging. It is unrelated to SSH Connection Logging, which is the audit feature that records SSH sessions. See Logging on the Troubleshooting page for the distinction between the two.