Athenode

Athenode Pro guide

Athenode Pro is the self-hosted team server of Athenode: one shared server on your PostgreSQL database, behind your reverse proxy, where a team keeps its projects, specifications, ToDo cards and plugins. It adds accounts with single sign-on, project roles and an audit trail to everything the local daemon does. Pro is sold per organisation as a seat pack, and it starts only with an activated license of that organisation.

What you need for Athenode Pro

  • An Athenode organisation with an active Pro seat pack. Billing for Athenode Pro explains how to buy one.
  • A server with Node.js 22.16 or later, or Node.js 24.
  • PostgreSQL 15 or later with its contrib modules, because Pro needs the pg_trgm extension.
  • A reverse proxy that terminates TLS for the address your team opens, such as Caddy or nginx.

Install Pro with an install token

Pro is published to Athenode's private npm registry. The organisation's install token, a deploy token that can only read that registry, installs it.

  1. On the organisation's page in your Athenode account, select Create install token.

  2. The Install token created dialog shows the token and the .npmrc lines for the registry. Copy both, because the token is shown once.

  3. Put the .npmrc lines into an .npmrc file in the directory you install from. They look like this, with the registry's project id in place of <id>:

    @athenode:registry=https://gitlab.iskelo.com/api/v4/projects/<id>/packages/npm/
//gitlab.iskelo.com/api/v4/projects/<id>/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

  4. Install the package with the token in the environment:

    GITLAB_NPM_TOKEN=<token> npm install -g @athenode/athenode-pro

The .npmrc maps the whole @athenode scope to the registry. Keep it in a directory of its own, so that installs of the public @athenode/cli elsewhere on the machine still come from npm.

Activate the organisation's license

Pro needs a license key of your organisation. A license token, created with Create license token on the organisation's page, is exchanged for a key and renews it automatically.

export ATHENODE_DATABASE_URL=postgres://athenode:secret@db.internal:5432/athenode
ATHENODE_LICENSE_TOKEN=<license token> athenode-pro license activate
athenode-pro license status

license activate needs only the database and works before the first start. It stores the token encrypted and renews the key daily, and hourly in the last week before it expires. Without a valid key Pro does not start and names the command to run. On a machine without internet access, select Download license key on the organisation's page and import the file with athenode-pro license import --file license.key.

The key lists the modules your seat pack licenses and the number of seats. Every enabled account takes one seat, the first administrator included. Pending invitations take none.

Start Pro behind your reverse proxy

Pro needs its public URL, the https origin your team opens, and the address of the proxy in front of it.

athenode-pro start --public-url https://athenode.example.com --trusted-proxy 10.0.0.2
athenode-pro status
athenode-pro doctor

The public URL has no path. Every request must address its host, and a browser request must come from its origin. Pro listens on port 3717 by default and speaks plain HTTP. The proxy terminates TLS, passes the original Host and Origin headers, passes the WebSocket upgrade on /api/realtime and keeps long requests open, because an MCP call can wait for minutes. A Caddy site needs no more than this:

athenode.example.com {
  reverse_proxy 127.0.0.1:3717 {
    flush_interval -1
  }
}

Pro's data folder is ~/.athenode-pro, apart from the free daemon's ~/.athenode. It holds the master key that encrypts stored secrets. Back it up separately from the database.

Sign in your team

On the first start Pro prints a one-time setup link to the console and to its log. Open it and create the first administrator.

  • Administrators invite people with one-time invitation links that are valid for 7 days. With SMTP configured in Settings, the links are emailed.
  • One OpenID Connect provider, such as Keycloak, Google, Okta or Entra ID, can sign accounts in next to the built-in ones. An administrator configures it in Settings with the issuer URL, the client ID and the client secret, and registers the redirect address the page shows.
  • Each account can turn on two-factor sign-in with an authenticator app, and an administrator can make it mandatory.

Project roles in Athenode Pro

Every account creates projects and becomes their owner. A project's owners and the administrators grant accounts and groups a role on the project's Members page.

Role What it can do in a project
Viewer Read the specifications, ToDo cards and plugins
Editor Also change the specifications, ToDo cards and plugins
Owner Also delete a specification or a plugin, publish to the plugin library, manage the project's roles, rename and delete the project

Administrators have owner rights on every project. An account without a role sees nothing of the project. A group linked to a value of the single sign-on groups claim gets its members at each sign-in.

Connect the CLI and AI tools to Pro

Bind a repository to a project on the team server with the server's public URL:

athenode init --server https://athenode.example.com

The CLI opens the browser to sign you in and keeps the tokens in ~/.athenode/credentials.json in your home folder, never in the repository. Your AI tools sign in to /api/mcp themselves with OAuth when they first connect, so no token goes into their configuration. athenode-pro mcp-config --project <id> prints the snippet for each AI tool.

Run Pro in an isolated network

Everything works without internet access except the plugin library and imports. Import the license key by hand. New projects get the standard Athenode plugin from the copy bundled with the release. Lower ATHENODE_CLOUD_FETCH_TIMEOUT_MS to 300 so that creating a project does not wait for the library.