For AI agents: the complete documentation index is available at https://payhon.github.io/AppKernia/en-US/llms.txt, the full documentation bundle is available at https://payhon.github.io/AppKernia/en-US/llms-full.txt, and this page is available as Markdown at https://payhon.github.io/AppKernia/en-US/guide/akone.md.
AppKernia

Install and deploy akone

akone puts the Go service, embedded Admin assets, operational commands, and OpenAPI CLI in one executable. When you run the native binary directly, its smallest setup uses local SQLite and does not require PostgreSQL, Node.js, or Docker. The npm installation method requires Node.js 18 or later.

Current release statusAppKernia has not published a public GitHub Release, npm package, or Homebrew Formula. The channel commands below document the implemented release paths; a source build is the only path available today. Use the matching preview command after the first Preview is published.

Choose an installation method

Available now

Requires Go 1.26.5, Node.js 24, and pnpm 11. The binary embeds Admin and starts with SQLite by default.

git clone https://github.com/Payhon/AppKernia.git
cd AppKernia
corepack enable
pnpm install --frozen-lockfile
make build-akone
mkdir -p "$HOME/.local/bin"
install -m 0755 ./server/bin/akone "$HOME/.local/bin/akone"
export PATH="$HOME/.local/bin:$PATH"
akone version --json

The PATH change affects only this terminal. Persist it in your shell profile if needed.

The Shell installer supports macOS and Linux on amd64 and arm64. npm also supports Windows amd64. Homebrew will be available only after macOS notarization, Windows signing, and stable releases are enabled. The installer never invokes sudo, edits PATH, or registers a system service.

Whichever method you use, first confirm that the expected version is running:

akone version --json

First start

Create a local administrator first. The command reads a password of at least 12 characters from the interactive terminal without putting it in command arguments or shell history:

akone bootstrap-admin --email admin@example.com --tenant-code local --tenant-name "Local Workspace" --display-name Administrator
akone serve

The service listens on 127.0.0.1:8080 by default. Open:

Without database configuration, akone creates data/appkernia.db next to the actual native executable. That is convenient for a manually placed binary and local evaluation. npm, Homebrew, and automated upgrades may move the executable directory, so a long-running deployment should use a separate stable data path.

Keep SQLite data in a stable location

On Unix and macOS, set a user data path for the current terminal session:

export AK_SQLITE_PATH="$HOME/.local/share/appkernia/appkernia.db"
akone bootstrap-admin \
  --email admin@example.com \
  --tenant-code local \
  --tenant-name "Local Workspace" \
  --display-name Administrator
akone serve

In Windows PowerShell, use the current user's local application-data directory:

$env:AK_SQLITE_PATH = "$env:LOCALAPPDATA\AppKernia\data\appkernia.db"
akone bootstrap-admin `
  --email admin@example.com `
  --tenant-code local `
  --tenant-name "Local Workspace" `
  --display-name Administrator
akone serve

These variables affect only the current terminal. Persist the same variable in the service manager or use YAML when deploying a service.

Use YAML configuration

Keep the configuration file in a location that does not change when the binary is upgraded:

akone config init --output ./akone.yml

At minimum, review the generated environment, listen address, public address, absolute SQLite path, and security keys. Production must not use development-time ephemeral keys. Fill the matching auth.* fields in an access-controlled configuration file, or supply AK_JWT_PRIVATE_KEY_BASE64, AK_LOGIN_PROTECTION_KEY_BASE64, and AK_CONFIG_MASTER_KEY_BASE64 through the service environment.

Validate the edited file, then use that same configuration for initialization and startup:

akone config validate --file ./akone.yml
akone --config ./akone.yml bootstrap-admin \
  --email admin@example.com \
  --tenant-code local \
  --tenant-name "Local Workspace" \
  --display-name Administrator
akone --config ./akone.yml serve

Precedence is: non-secret command-line flags > AK_* environment variables > YAML > defaults. Keep the configuration file at mode 0600 on Unix and macOS. On Windows, place it in a directory readable only by the current user or service account.

Run as a managed service

The installer installs only the executable; it does not create an operating-system user, service, or reverse proxy. A production deployment should at least:

  1. Run under a dedicated, low-privilege service account that owns only the configuration, data, and required log directories.
  2. Use a stable absolute SQLite path and run only one akone instance that writes to that database.
  3. Keep akone bound to loopback and terminate TLS in Caddy, Nginx, or the existing gateway.
  4. Put secrets in access-controlled configuration or service environment—not command arguments, the repository, or logs.
  5. Configure graceful SIGTERM shutdown, restart on failure, and a reasonable stop timeout.
  6. Verify configuration, administrator sign-in, Readiness, logs, backup, and recovery before launch.

This minimal Linux unit is a starting point. An operator must first create the appkernia account, directories, and /etc/appkernia/akone.yml, then adjust paths for the host:

/etc/systemd/system/appkernia.service
[Unit]
Description=AppKernia akone
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=appkernia
Group=appkernia
ExecStart=/usr/local/bin/akone --config /etc/appkernia/akone.yml serve
Restart=on-failure
RestartSec=5s
TimeoutStopSec=30s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/appkernia

[Install]
WantedBy=multi-user.target

This is only a process-supervision example. It does not create users, certificates, network policy, or backups. Use launchd on macOS or your organization's Windows Service manager on Windows, while passing the same YAML file or stable AK_* environment variables.

Back up and upgrade

SQLite runs in WAL mode. For a dependable file-level backup, stop the service, copy the entire dedicated data directory, and then start the service again. Do not copy only the .db file while the process is running. Before an upgrade, also retain the current binary, configuration, and a restorable database backup.

Upgrade in this order:

  1. Record akone version --json, run akone config validate --file /etc/appkernia/akone.yml, and take an offline backup. Substitute the actual configuration path when it differs.
  2. Replace the executable through the same installation channel without moving configuration or data.
  3. Start the service and check Readiness, sign-in, and logs.
  4. SQLite schema migrations are forward-only. To roll back, restore both the old binary and the pre-upgrade backup instead of running an old binary against the new schema.

SQLite and PostgreSQL boundaries

SQLite currently covers health checks, embedded Admin, administrator authentication and personal sessions, and Dashboard. It fits single-host evaluation and lightweight deployment. API Clients, Apps, content, notifications, push, and job queues do not yet have SQLite-equivalent implementations; enabling unsupported features fails at startup.

Use PostgreSQL for the complete business modules, workers, multiple instances, or higher concurrency. Follow source development or the Docker development stack to apply migrations and core seed data. Changing database mode does not change the Admin or OpenAPI authorization boundaries.