Configuration of the athenode daemon

The athenode daemon keeps its data in one folder on your machine and takes its settings from command-line options, environment variables and the config.json in that folder, in that order of precedence. The athenode daemon is the local Athenode server that the athenode package installs: it keeps your projects on your machine and serves the web UI and the Athenode MCP server at http://127.0.0.1:3717. Install Athenode covers installing and running it.

The data folder and its files

The data folder is the folder where the daemon keeps its data: ~/.athenode by default, C:\Users\<you>\.athenode on Windows. Choose another folder with --data-dir <dir> on a daemon command or with ATHENODE_DATA_DIR. The data folder cannot be set in config.json, because that file is inside it.

Path in the data folder	What it holds
`db/`	Your projects with their specifications, ToDo cards, plugins and SSH connections.
`master.key`	The master key, unless you keep it elsewhere (see the master key).
`config.json`	The daemon's settings (see the configuration file). Optional.
`athenode.lock`	The record of the running daemon, with its port. One daemon runs per data folder.
`logs/athenode.log`	Errors that stopped the daemon at start or made it exit.
`logs/daemon.out.log`, `logs/daemon.err.log`	The daemon's output when the service runs it on macOS.
`logs/daemon.log`	The daemon's output when the service runs it on Windows.
`backups/`	The copies the daemon saves before it converts your data for a new version, and the files `athenode restore --force` moves aside. Backup and restore describes both.
`update-check.json`	When the `athenode` command last checked for a new version, and the version it found.

The daemon creates the folder, logs/ and backups/ so that only you can read them. On Linux and macOS it warns at start when the folder, db/, master.key, config.json or athenode.lock can be read by other users, and the warning gives the chmod command that fixes it: 700 for a folder, 600 for a file. athenode doctor runs the same check.

The CLI keeps its sign-ins to Athenode Pro servers in the system's keychain, and in ~/.athenode/credentials.json where there is none. That file is always in your home folder, whatever the data folder. Connect to Athenode Pro describes the sign-in.

Configuration file of the daemon

The daemon reads config.json in the data folder when it starts, so restart the daemon after you change the file. The file holds one JSON object. A key the daemon does not know is reported with a warning and ignored. A value outside its range stops the start with a message that begins "Athenode cannot start:" and names the key.

{
  "port": 3800,
  "library": { "fetchTimeoutMs": 10000 },
  "imports": { "githubToken": "<token>" },
  "disableHealthChecks": true
}

Key	Value	Default	What it sets
`port`	An integer from 1 to 65535	`3717`	The port of the web UI and the MCP server. `athenode service install --port <n>` writes this key.
`masterKeyFile`	A path	`master.key` in the data folder	The file that holds the master key.
`publicUrl`	An `http` or `https` URL without a path, such as `http://host.docker.internal:3717`	None	The address under which an AI tool in a container or a virtual machine reaches the daemon (see requests from other machines and containers).
`library.fetchTimeoutMs`	100 to 120000 milliseconds	`5000`	How long the daemon waits for an answer from the plugin library. When a project is created and the library does not answer in that time, the new project gets the copy of the standard plugin that comes with the package.
`imports.githubToken`	A token of up to 1,000 characters	None	The GitHub token for imports, used when you have set no personal GitHub token on the Imports page. Without a token, GitHub allows 60 requests an hour.
`imports.gitlabToken`	A token of up to 1,000 characters	None	The GitLab.com token for imports, used when you have set no personal GitLab token on the Imports page.
`disablePoll`	`true` or `false`	`false`	Stops the regular status checks of your SSH connections.
`disableJobSync`	`true` or `false`	`false`	Stops the regular sync of the output and state of background jobs on your SSH hosts.
`disableHealthChecks`	`true` or `false`	`false`	Stops the scheduled health checks of your services. A check you run by hand runs as usual.

The library and imports objects accept only the keys in the table. The Imports page describes the personal tokens. Service alert webhooks are a feature of Athenode Pro Team and up, so the daemon reports serviceCheckWebhookUrl and serviceCheckWebhookSecret as unknown keys and ignores them. Configure Athenode Pro lists them.

After you change the port, run athenode init --project <id> in each repository bound to the daemon. The binding and the MCP entries that init wrote name the old port, and init with the project's id binds the repository to the same project on the new port.

Initial values of the SSH gateway settings

Each SSH gateway setting can be given in config.json under its key, or as its environment variable. The SSH gateway is the part of Athenode through which your AI agent runs commands and transfers files on your SSH hosts, each action approved by you or by a rule you set.

These values are initial values. The daemon stores every setting when it first starts with an empty data folder, and the stored value is used from then on. To change a setting after that, use the server's Settings page in the web UI, as History and gateway settings describes. The settings marked "No" in the last column have no field on that page and keep the value they had at the first start.

Key	Variable	Default	Range	On the Settings page
`approvalTimeoutMs`	`ATHENODE_APPROVAL_TIMEOUT_MS`	600000 (10 minutes)	1 to 86400000	Yes
`auditRetentionDays`	`ATHENODE_AUDIT_RETENTION_DAYS`	90	1 to 3650	Yes
`statusPollIntervalMs`	`ATHENODE_STATUS_POLL_INTERVAL_MS`	60000	5000 or more	Yes
`sshIdleTimeoutMs`	`ATHENODE_SSH_IDLE_TIMEOUT_MS`	300000	1000 or more	Yes
`serviceCheckHistoryDays`	`ATHENODE_SERVICE_CHECK_HISTORY_DAYS`	7	1 to 3650	Yes
`serviceCheckHistoryMaxRuns`	`ATHENODE_SERVICE_CHECK_HISTORY_MAX_RUNS`	1000	10 to 100000	Yes
`jobSyncIntervalMs`	`ATHENODE_JOB_SYNC_INTERVAL_MS`	3000	500 to 3600000	No
`killGraceMs`	`ATHENODE_KILL_GRACE_MS`	5000	0 to 60000	No
`execOutputLimitBytes`	`ATHENODE_EXEC_OUTPUT_LIMIT_BYTES`	8388608 (8 MiB)	64 KiB to 12 MiB	No
`execStoredOutputLimitBytes`	`ATHENODE_EXEC_STORED_OUTPUT_LIMIT_BYTES`	67108864 (64 MiB)	16 MiB to 256 MiB	No
`transferUrlTtlSec`	`ATHENODE_TRANSFER_URL_TTL_SEC`	600	30 to 86400	Yes
`transferMaxBytes`	`ATHENODE_TRANSFER_MAX_BYTES`	1073741824 (1 GiB)	1 MiB to 64 GiB	Yes

Times ending in Ms are in milliseconds and those ending in Sec in seconds. Commands, files and jobs explains what the limits of commands, jobs and transfers do.

The master key

The master key is the key that encrypts the secrets the daemon stores: the passwords, private keys and passphrases of your SSH connections, your personal GitHub and GitLab tokens and the daemon's sign-in to the plugin library. The first start of the daemon creates it as master.key in the data folder and prints "Created a new master key" with the file's path.

The daemon takes the key from the first of these that is set:

ATHENODE_MASTER_KEY, the key itself, base64-encoded.
ATHENODE_MASTER_KEY_FILE, or masterKeyFile in config.json, the path of a file that holds the key. The variable wins over the key in config.json.
master.key in the data folder.

A key is 32 bytes, written in base64. The daemon checks the key against your data at every start. A key that does not match stops the start with a message that names where the key came from, and athenode doctor reports the same under "Master key check". When no key is found and your data holds encrypted secrets, the daemon does not create a new key and asks you to restore master.key or to set one of the two variables.

Warning

Without the original master key, the stored passwords, keys and tokens cannot be decrypted. Back the key up separately from your data.

athenode backup puts the key in effect into the backup archive, wherever it came from. Backup and restore describes backing up and restoring the key.

Environment variables

Each setting is taken from the first source that sets it: a command-line option, then an environment variable, then config.json, then the default. --port wins over ATHENODE_PORT, which wins over port in config.json.

Variable	What it sets
`ATHENODE_DATA_DIR`	The data folder, as `--data-dir` does.
`ATHENODE_PORT`	The port of the daemon, from 1 to 65535, as `--port` does.
`ATHENODE_MASTER_KEY`	The master key, base64-encoded. Read from the environment only.
`ATHENODE_MASTER_KEY_FILE`	The file that holds the master key.
`ATHENODE_NO_UPDATE_CHECK`	With the value `1`, turns off the version checks of the daemon and of the `athenode` command.
`ATHENODE_CLOUD_FETCH_TIMEOUT_MS`	The wait for an answer from the plugin library, in milliseconds, as `library.fetchTimeoutMs` does.
`ATHENODE_GITHUB_TOKEN`	The GitHub token for imports, as `imports.githubToken` does.
`ATHENODE_GITLAB_TOKEN`	The GitLab.com token for imports, as `imports.gitlabToken` does.
`ATHENODE_DISABLE_POLL`	With `1`, `true` or `yes`, stops the status checks of SSH connections, as `disablePoll` does.
`ATHENODE_DISABLE_JOB_SYNC`	With `1`, `true` or `yes`, stops the sync of background jobs, as `disableJobSync` does.
`ATHENODE_DISABLE_HEALTH_CHECKS`	With `1`, `true` or `yes`, stops the scheduled health checks, as `disableHealthChecks` does.
`ATHENODE_PRO_TOKEN`	A personal access token, created on the Account page of an Athenode Pro server, that the CLI sends to that server in place of its stored sign-in, for example in CI.
`ATHENODE_CREDENTIALS_STORE`	With the value `file`, the CLI keeps its Pro sign-ins in `~/.athenode/credentials.json` and not in the system's keychain.
`ATHENODE_SHOW_PRO_CAPABILITIES`	With `0`, hides what Athenode Pro adds from the web UI, as the Show Pro capabilities switch does. It sets the switch when the daemon stores it the first time, and the switch decides from then on.
`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`	The proxy for the daemon's requests to the internet (see proxies).

The variables of the SSH gateway settings are in the table of those settings. ATHENODE_PRO_TOKEN and ATHENODE_CREDENTIALS_STORE concern the CLI's sign-in to Athenode Pro, which Connect to Athenode Pro covers.

Variables and the service

A daemon that the service starts does not see the variables you set in a terminal. Of the Athenode variables, the service passes on ATHENODE_DATA_DIR only, and only when you gave a data folder to athenode service install with --data-dir or ATHENODE_DATA_DIR. Put the settings of a service-run daemon in config.json, or run the daemon with athenode start in a terminal where the variables are set. The master key itself cannot be put in config.json, so a service-run daemon that keeps its key outside the data folder names the key's file with masterKeyFile.

Proxies

The daemon sends its requests to the internet through the proxy that HTTPS_PROXY or HTTP_PROXY names, except for the hosts that NO_PROXY lists. That covers the requests to the plugin library, the MCP catalogue and the skills.sh search, and the imports from GitHub, GitLab and other addresses. The proxy can be set only in the environment, so run a daemon behind a proxy with athenode start in a terminal where the variables are set, because the service does not pass the variables of your terminal on.

What Athenode stores lists the requests the daemon makes without being asked.

Requests from other machines and containers

The daemon listens on 127.0.0.1 only and answers requests addressed to 127.0.0.1:<port> or localhost:<port>. An AI tool reaches it from the same machine, at the address that init writes into the tool's MCP configuration.

An AI tool in a container or a virtual machine on your computer reaches the daemon under another address, such as http://host.docker.internal:3717. To let it in:

Set that address as publicUrl in config.json: an http or https URL without a path, query or fragment.
```
{ "publicUrl": "http://host.docker.internal:3717" }
```
Restart the daemon with athenode service restart, or stop and start it in its terminal.
Make the daemon's port reachable under that address from the container, with a port forwarding that you set up, because the daemon listens on 127.0.0.1 only.
Run athenode mcp-config --project <id> and give the AI tool in the container the MCP entry it prints, which names the public URL.

The daemon then answers requests addressed to the public URL's host as well, and uses the public URL in every address it gives out: the web UI, the MCP entries of mcp-config and the transfer URLs of the SSH gateway. The address must therefore also work where those links are opened, such as in your browser. Repositories bound with http://127.0.0.1:<port> stay bound.

The daemon has no sign-in, so every program that reaches the public URL can use it. A team whose members or agents work on other computers uses Athenode Pro, which runs on a server with its own address and signs everyone in.

Operating system specifics

	Linux	macOS	Windows
Data folder	`~/.athenode`	`~/.athenode`	`C:\Users\<you>\.athenode`
Service entry	`~/.config/systemd/user/athenode.service`, or under `$XDG_CONFIG_HOME` when it is set	`~/Library/LaunchAgents/com.athenode.daemon.plist`	`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\athenode.vbs`
Logs of the service	`journalctl --user -u athenode`	`logs/daemon.out.log` and `logs/daemon.err.log` in the data folder	`logs\daemon.log` in the data folder
After a crash	The service starts the daemon again after 5 seconds	The service starts the daemon again	The daemon starts again at the next login
Keychain for Pro sign-ins	The Secret Service, such as GNOME Keyring or KWallet, through `secret-tool`, in a session with a desktop bus	The login Keychain	The Credential Manager
Permission warnings	Yes	Yes	No

On Linux, athenode service install prints the command loginctl enable-linger $USER, which keeps the daemon running when you are not logged in. Without a systemd user instance, as in WSL without systemd and in containers, the command stops with a message that says how to start the daemon in a terminal or turn on systemd in WSL.

On Linux over SSH, in CI and in containers, there is no desktop bus, so the CLI keeps its Pro sign-ins in ~/.athenode/credentials.json.

On Windows, the SSH gateway cannot use an ssh-agent, so a connection there signs in with a password, a stored private key or a key file. The SSH gateway describes the login methods of a connection.

Last updated: 2026-10-30