AKADATA LIMITED

AKAMAN Running as a Service

Run AKAMAN as a persistent HTTP/webMCP service with systemd or OpenRC: install, configure, bind addresses, authentication, firewall, and TLS guidance.

AKAMAN

A small Linux C utility that retrieves the compact documentation fragment an AI agent needs from the host where it is running.

Download AKAMAN v0.1.0 source →

Running AKAMAN as a service

You probably do not need this page.

For local agents such as Codex, OpenCode, Claude Code or Gemini CLI, AKAMAN runs as an ordinary stdio MCP server — no daemon, no init system, no configuration file. The one-line setup is on the Overview. Read this page only if you want AKAMAN reachable as an authenticated HTTP/webMCP endpoint over a network.

AKAMAN usually does not need to run as a background service. For local clients such as Codex, OpenCode, Claude Code, Gemini CLI and other agents that support a local stdio MCP server, the client launches AKAMAN when it needs it:

/usr/local/bin/akaman --mcp

Communication then happens over standard input and standard output. There is no listening socket and no init-system service is required.

AKAMAN also provides an optional authenticated HTTP/webMCP transport. That is the mode for which a persistent service is useful: the server must stay running independently so a remote or network client can reach it.

Changing the listener changes the security boundary.

AKAMAN defaults to 127.0.0.1:8931 — loopback only, reachable solely from the same host. Binding to 0.0.0.0, ::, a LAN address, or any public interface deliberately exposes the MCP endpoint to other systems. Do not expose an MCP service to the Internet simply because the software makes it technically possible; bearer authentication is not a substitute for a firewall or TLS.

Local stdio MCP — no service needed

For clients such as Codex, OpenCode, Claude Code and other agents which launch a local stdio MCP server:

/usr/local/bin/akaman --mcp

No system service is required. The MCP client launches AKAMAN itself and communicates through stdin/stdout.

Codex
   │
   │ launches process
   ▼
/usr/local/bin/akaman --mcp
   │
   └── stdin/stdout

The systemd and OpenRC service scripts are not intended for this use case. Do not install a daemon when you only need local stdio MCP.

HTTP/webMCP — a service keeps it running

The service wrappers exist for:

akaman --http

where AKAMAN needs to remain running independently as an authenticated HTTP MCP endpoint.

MCP client
    │
    │ HTTP + bearer authentication
    ▼
persistent AKAMAN service
    │
    ▼
local documentation

This is where systemd or OpenRC becomes useful.

Before installing a service

Confirm AKAMAN itself works, and that the HTTP transport starts, before introducing an init system:

command -v akaman
akaman --http

By default AKAMAN binds its HTTP transport to 127.0.0.1:8931. Keeping the loopback address means the service can only be reached from the same host. Stop the foreground server with Ctrl-C before continuing.

systemd

The example unit is supplied as contrib/systemd/akaman.service. It starts /usr/local/bin/akaman, runs the HTTP transport, runs in the foreground under systemd supervision, restarts after an unexpected failure, and starts automatically once enabled. This is the full unit as shipped:

[Unit]
Description=AKAMAN MCP HTTP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/akaman --http
Restart=on-failure
RestartSec=2
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

The hardening directives present in the unit are:

NoNewPrivileges=yes — prevents the process gaining new privileges.
ProtectSystem=strict — the filesystem is mounted read-only except for a few paths; AKAMAN does not need to write to the system.
ProtectHome=yes — /home, /root and /run/user are hidden from the service.
PrivateTmp=yes — the service gets its own private /tmp.

The unit does not use DynamicUser=; AKAMAN supports systems where that systemd feature may be unavailable (including musl-based systemd builds), and it does not assume a dedicated akaman user or group exists.

Install

sudo install -Dm644 contrib/systemd/akaman.service \
    /etc/systemd/system/akaman.service

sudo systemctl daemon-reload
sudo systemctl enable --now akaman.service

Status and logs

systemctl status akaman.service
journalctl -u akaman.service -f

Stop and disable

sudo systemctl stop akaman.service
sudo systemctl disable akaman.service

Changing the command without editing the unit

Configuration changes should normally use an override rather than editing the installed unit:

sudo systemctl edit akaman.service

When overriding ExecStart, systemd requires the inherited value to be cleared first:

[Service]
ExecStart=
ExecStart=/usr/local/bin/akaman --http=127.0.0.1:8931 --conf /etc/akaman/akamcp.conf

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart akaman.service

OpenRC

Two files are supplied: contrib/openrc/akaman (the init script) and contrib/openrc/akaman.confd (administrator configuration). The separation keeps runtime arguments out of the init script.

The init script:

#!/sbin/openrc-run

name="AKAMAN MCP HTTP Server"
command="/usr/local/bin/akaman"
command_args="--http"
command_background="yes"
pidfile="/run/${RC_SVCNAME}.pid"

depend()
{
    need net
}

It runs /usr/local/bin/akaman in the background (command_background="yes") and records its pid at /run/akaman.pid (via ${RC_SVCNAME}). It declares need net because the HTTP transport is only useful once the network is up.

The configuration file:

AKAMAN_ARGS="--http"

AKAMAN_ARGS holds the arguments passed to the server. To change the bind address or configuration path, set AKAMAN_ARGS in /etc/conf.d/akaman — for example AKAMAN_ARGS="--http=127.0.0.1:8931". In the shipped v0.1.0 script, command_args is currently set directly to --http; for the confd to drive the arguments, change that line in /etc/init.d/akaman to command_args="${AKAMAN_ARGS}". Both edits are small, and the project documents the ${AKAMAN_ARGS} pattern as the intended form.

Install

sudo install -Dm755 contrib/openrc/akaman /etc/init.d/akaman
sudo install -Dm644 contrib/openrc/akaman.confd /etc/conf.d/akaman

Start and manage

sudo rc-update add akaman default
sudo rc-service akaman start
rc-service akaman status
sudo rc-service akaman restart
sudo rc-service akaman stop
sudo rc-update del akaman default

To change the listener or configuration path, edit /etc/conf.d/akaman rather than modifying the init script.

Why both wrappers exist

systemd is common on many Linux distributions. OpenRC is used by distributions such as Alpine, Gentoo and AKADATA/Saphira-style systems. AKAMAN itself does not depend on either init system; these files are optional convenience wrappers, and AKAMAN can always be run manually with akaman --http. The init systems merely supervise that same process.

Configuration

See the Configuration page for full detail. For HTTP mode the default configuration location is /etc/akaman/akamcp.conf; select another file with --conf PATH. The file supplies a single APIKEY= assignment. API-key configuration is not required for normal CLI or stdio MCP use.

Authentication

The HTTP transport authenticates clients with a bearer key in the Authorization header. The key is read from the configuration file; without it the server refuses to start. Bearer authentication identifies and authorises the client — it does not encrypt the HTTP traffic.

Default network bind

AKAMAN's HTTP mode defaults to 127.0.0.1:8931. This is deliberate: at the default address only applications running on the same host can reach the service. That is a security boundary, and it is the safe starting point.

To listen on another address, pass it explicitly:

akaman --http=127.0.0.1:8931

Changing the listener to a LAN, public, wildcard (0.0.0.0, ::) or other externally reachable address changes the security boundary. AKAMAN does not need public Internet exposure in order to operate.

Changing the listener changes the security boundary. — A network-accessible MCP server is a service endpoint. Treat it like one.

Firewall and network consequences

For 127.0.0.1:8931, no inbound firewall opening is normally required. For a LAN or externally reachable address, an administrator must deliberately decide which systems are permitted to connect. Bearer authentication does not replace a firewall: it controls who may call the API, not which hosts may reach the port. The preferred progression is localhost, then a trusted private network where required, then authenticated and encrypted remote access where deliberately designed — rather than exposing the HTTP listener directly to the Internet. No distro-specific firewall recipe is prescribed here; the responsibility and risk are what matter.

TLS

Bearer authentication authenticates the client. It does not encrypt HTTP traffic. When AKAMAN HTTP traffic crosses an untrusted network, use appropriate TLS protection — for example an intentionally configured reverse proxy or another secure transport layer. AKAMAN itself does not provide TLS; do not assume it does.

Troubleshooting

Run AKAMAN manually before troubleshooting the init system:

/usr/local/bin/akaman --http --conf /etc/akaman/akamcp.conf

Then check the service-specific diagnostics.

systemctl status akaman.service
journalctl -u akaman.service

rc-service akaman status

ss -ltnp | grep 8931
ls -l /etc/akaman/akamcp.conf
command -v akaman

When an explicit bind address is rejected, test the same address directly from the command line: AKAMAN validates HTTP bind addresses and exits rather than silently accepting an invalid value.