For AI agents: the complete documentation index is available at https://docs.appkernia.com/en-US/llms.txt, the full documentation bundle is available at https://docs.appkernia.com/en-US/llms-full.txt, and this page is available as Markdown at https://docs.appkernia.com/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.

0.6.0 distributionOfficial archives use static.appkernia.com with a fixed /akone/latest.sh installer. macOS and Windows artifacts do not yet have native signing. This distribution does not update npm, Homebrew, or GitHub Releases.

Choose an installation method

0.6.0

For macOS and Linux on amd64 or arm64; the installer verifies SHA-256.

curl -fsSL https://static.appkernia.com/akone/latest.sh | sh
export PATH="$HOME/.local/bin:$PATH"
akone version --json

The installer verifies the archive checksum, archive version, and embedded binary version.

Pin a version or choose a destination:

curl -fsSL https://static.appkernia.com/akone/latest.sh -o install.sh
sh install.sh --version 0.6.0 --install-dir "$HOME/.local/bin"

Manual downloads use https://static.appkernia.com/akone/0.6.0/akone_0.6.0_<os>_<arch>.tar.gz; the Windows archive is akone_0.6.0_windows_amd64.zip. The same directory contains checksums.txt and install.sh. Each installer pins its default version, verifies the archive and embedded version, and atomically replaces the executable.

The Shell installer supports macOS and Linux on amd64 and arm64; Windows amd64 uses the versioned ZIP archive. Homebrew remains unpublished, and npm is a separate historical Preview channel. 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

The current source build supports SQLite health checks, embedded Admin, administrator authentication and personal sessions, Dashboard, and API Client management and remote authentication. Apps, content, notifications, push, and job queues do not yet have SQLite-equivalent implementations; enabling unsupported features fails at startup. See remote clients for multi-server profiles and Agent usage. These capabilities are included in the 0.6.0 build.

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.