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/remote-client.md.
AppKernia

Multiple servers and remote CLI

This page describes the current source build. Existing public preview artifacts may not include these commands. Installation channels and download links are unchanged; see installation and deployment.

akone can run only as a client: it does not need a local serve, administrator, or database. Create an API Client on the target server, generate an AppSecret, bind a real user for Agent calls, and grant client permissions and application access. Effective permissions remain the intersection of client and bound-user permissions.

Configure and switch

akone auth configure --profile production \
  --server https://api.example.com --client-id ak_xxx
# Enter AppSecret at the hidden prompt, not in command arguments

akone auth configure --profile local \
  --server http://localhost:8080 --client-id ak_yyy
akone auth list
akone auth use production
akone auth status --profile production
akone api call getAdminDashboardSummary --profile production

The first profile becomes the default; adding another does not switch it. Selection order is --profile > AK_PROFILE > current default. A missing name fails without contacting a different server. auth status performs a real token exchange and reports the server, Client ID, and authentication result without exposing secrets or tokens. Successful authentication does not grant every business permission.

An origin may include a port, such as https://api.example.com:8443, but no API path, query, fragment, or embedded credentials. Remote servers require HTTPS; HTTP is limited to localhost/loopback. Certificates are verified, with no verification bypass or redirect following.

api call --server URL only asserts the selected credential origin. It cannot forward an existing secret to another domain. Configure another profile to access another server. Changing an existing profile's server requires --replace and complete new credentials.

akone auth configure --profile production --replace \
  --server https://new-api.example.com --client-id ak_new
akone auth remove local --yes

Removal only deletes local configuration, not the server client. Removing the default leaves no default; you must explicitly choose another server. Revoke a secret, disable the client, or unbind its user on the target server to withdraw access.

Automation and AI Agents

Prefer human-configured profiles and an explicit --profile production in Agent calls. Never put AppSecret into prompts or tool arguments. For non-interactive initialization, pipe a secret manager's output to auth configure ... --secret-stdin.

For file-free automation, inject all three variables together through your CI secret mechanism:

  • AK_SERVER_URL: target server origin.
  • AK_CLIENT_ID: Client ID issued by that server.
  • AK_CLIENT_SECRET: corresponding AppSecret.

Then run akone api call getAdminDashboardSummary. The complete tuple is process-local and never saved. Partial tuples fail and cannot be combined with --profile or AK_PROFILE. Missing fields are never filled from a file.

akone api list
akone api describe getAdminDashboardSummary
akone api call getAdminDashboardSummary --profile production \
  --query range=7d --timeout 20s

api list/describe uses the embedded OpenAPI and labels that source on stderr; it does not discover remote operations. Unsupported operations on an older server or SQLite fail without switching to localhost or retrying writes. Exit codes are 0 for success, 1 for runtime/authentication failure, and 2 for usage errors. Stable CLI.AUTH.* codes accompany translated messages; set AK_LOCALE=en-US for English.

Credential storage and migration

The default file is AppKernia/credentials.json inside the operating system's user configuration directory. Override it with --credentials-file or AK_CREDENTIALS_FILE. It is independent of server YAML and contains plaintext AppSecret: keep Unix files at mode 0600 and use a current-user-only ACL directory on Windows. Never commit it to Git.

Legacy single-credential files map read-only to default. The first edit backs up the original bytes to credentials.json.v1.bak, then atomically migrates the file. Protect the backup as a secret too. Symlinks, non-regular files, unsafe permissions, and conflicting backups are rejected. File locks serialize modifications across CLI processes.

Deployment and database boundaries

Keep the server on loopback behind a TLS reverse proxy as described in deployment. Configure the proxy's HTTPS origin in the client, not the internal listen address. Serve the API directly instead of redirecting authentication to another domain. CIDR rules use the connection address actually observed by the service; combine them with gateway access controls rather than trusting arbitrary forwarding headers.

Current-source SQLite v2 supports API Client management, token exchange, user binding, permission/application grants, and the three Dashboard Agent operations. Enable server-side features.api_clients or AK_API_CLIENTS_ENABLED to expose the client feature. Supporting management-page data sources and content/notification modules are not fully implemented in SQLite. Existing administrators can configure clients through the same management APIs; the entire Admin UI is not claimed as accepted.

Stop and back up SQLite before upgrading. Rollback requires both the old executable and pre-upgrade data. Client profiles do not alter server databases or plugin Bootstrap/TLS. Remote plugin management remains future work; current plugin dev does not accept a remote profile.