Install Athenode

Athenode runs on your machine as a local daemon: one background process that keeps your projects, specifications, ToDo cards and plugins in a database in your home folder. The athenode command installs it, binds a repository to one of its projects and writes the files your AI coding tools read. No account is needed for any of it.

Requirements for the local install

Node.js 22.16 or later, or Node.js 24. Check with node --version.
macOS, Linux or Windows. The daemon listens on 127.0.0.1 only and is not reachable from other machines.
Between 300 and 700 MB of free memory for the embedded database, which is PostgreSQL compiled to WebAssembly and installed with the package. Docker and a PostgreSQL server are not needed.

Install the package and the daemon

Install the package globally:
```
npm i -g athenode
```
Install the daemon as a service of your user:
```
athenode service install
```

The service starts the daemon now and at every login, without administrator rights. On Linux it is a systemd user unit, on macOS a launchd agent and on Windows a Startup entry that runs without a console window. On Linux, loginctl enable-linger $USER keeps the daemon running when you are not logged in. WSL without systemd and containers have no user systemd, and athenode service install says so.

athenode service status shows whether the service is installed and the daemon runs. The daemon's web UI is at http://127.0.0.1:3717. Use 127.0.0.1 and not localhost, because localhost can resolve to the IPv6 address, where the daemon does not listen.

Install one of the packages athenode and @athenode/cli globally, not both: both provide the athenode command. athenode init runs the same command without a global install, but the service needs the global athenode package.

Bind a repository with athenode init

athenode init binds a repository to a project of the daemon and installs the project's plugin for your AI tools. Run it in the root of the repository, because every later command looks for .athenode/config.json in the current directory.

cd your-repository
athenode init

init checks that the daemon runs and offers to install the service when it does not.
It picks a project. A new project is named after the directory, and --project <id> binds an existing one.
It asks which AI tools to install into, with the ones it finds in the directory selected.
It shows a plan of every file it will add, change or remove, and applies it when you confirm.

A new project starts with its own copy of the standard Athenode plugin, which holds the Athenode workflow. The plugin's MCP entry points your AI tools at the project on the daemon, http://127.0.0.1:3717/api/mcp?project=<id>. .athenode/config.json records the binding and the selected tools. It holds no token.

Install a plugin explains the install formats and the plan, and the Athenode CLI reference lists every option.

Keep the files current with athenode sync

Only the athenode command writes files into your repository. When the project's plugin changes, through the daemon's web UI or through your AI agent, run athenode sync in the repository. It regenerates the files from the daemon without asking any question.

athenode sync

An AI tool that holds a running session reads a changed plugin after a restart. athenode sync prints what each tool needs.

Back up and restore your data

Everything the daemon stores is in the data folder ~/.athenode (C:\Users\<you>\.athenode on Windows): the database, the master key that encrypts stored secrets, config.json and the logs.

athenode backup

athenode backup writes the whole data folder as one archive, athenode-backup-<version>-<time>.tar.gz, readable only by you. It holds the master key, so keep the archive as safe as the key itself. With the daemon running, the backup goes through the daemon and pauses writes while the database is copied.

To restore, stop the daemon and restore the archive into the data folder:

athenode stop
athenode restore athenode-backup-0.11.0-20261020T080000Z.tar.gz
athenode service restart

athenode restore refuses a backup of a newer version and a data folder that already holds a database, unless you add --force, which first moves the existing database and key into backups/ in the data folder. To move a single project to another machine or to an Athenode Pro server, use athenode project export and athenode project import in place of a whole backup.

Update Athenode

The daemon checks npm for a newer athenode at start and every 24 hours, and the athenode command checks at most once a day. When there is one, the web UI shows a notice and the command prints one line on standard error. Updating stays in your hands:

npm i -g athenode
athenode service restart

The first start of a version with database changes saves the database to backups/ in the data folder before it migrates. ATHENODE_NO_UPDATE_CHECK=1 turns both checks off.

Remove the service

athenode service uninstall removes the service entry and stops the daemon. The data folder stays where it is. Delete ~/.athenode yourself when you no longer need your projects, after a last athenode backup if you want to keep them.

Last updated: 2026-10-19