Akan Runtime

Akan applications run on a Bun-based runtime that connects app code, generated artifacts, server routes, and pages. The app entry point (main.ts) starts the runtime, and Akan handles the server shape behind it.

apps/myapp/main.ts

When Akan App starts, Akan Server prepares everything the app can serve. In practice, the runtime exposes four kinds of work.

Internal API (Queue, Timer, etc.): internal work that runs without a browser request.
API (HTTP, WebSocket): public communication for data requests and realtime updates.
SSR Pages (Web): web pages rendered by the server and sent to the browser.
CSR Page (Android, iOS): client-rendered pages used by mobile targets.

Runtime overview

One Akan App can run one or more Akan Server processes. AKAN_REPLICA controls how many server processes are started for each role, so the same app can scale web traffic and background work separately. For browser traffic, Akan App also load-balances requests across ready federation and all servers.

federation: serves browser traffic such as pages, API calls, and WebSocket connections.
batch: runs background work such as queues, timers, and scheduled jobs.
all: runs both federation and batch behavior in one server process. This is the simple local default.

Replica and server modes

A single Akan App has built-in clustering. You can run multiple server replicas and let Akan App distribute traffic, without setting up separate local load-balancing tools such as nginx, docker compose, or pm2.

Root-level Env Variables

The root .env file decides which organization, domain, environment, operation mode, and log level the app uses while it runs. Most projects keep these values stable, but changing them lets the same app behave like a local, debug, develop, or production-like service.

.env

Environment variables prefixed with AKAN_PUBLIC_ are public. They can be read by browser code, so never store secrets, private tokens, or credentials in them.

AKAN_PUBLIC_REPO_NAME

Project owner

Organization or repository namespace. Usually fixed for the project.

ex) akansoft

AKAN_PUBLIC_SERVE_DOMAIN

Public domain

Used when the app creates links, callbacks, and domain-based routes.

ex) "akanjs.com"

AKAN_PUBLIC_ENV

Data environment

Choose local, debug, develop, or main depending on which data set you want to use.

ex) local | debug | develop | main

AKAN_PUBLIC_OPERATION_MODE

Connection target

Choose whether clients connect to local runtime, edge paths, or cloud services.

ex) local | edge | cloud

AKAN_PUBLIC_LOG_LEVEL

Log detail

Choose how much runtime output you want to see in the terminal.

ex) trace | debug | info | warn | error

AKAN_LOG_FILE_LEVEL

File log detail

Choose how much structured Logger output is written to files. Defaults to trace, independent from terminal log level.

ex) trace | debug | info | warn | error

AKAN_LOG_TO_FILE

File logging

AkanApp writes gateway and child process logs to runtime/logs by default. Set this to 0 to disable file logging.

ex) 0 | 1

AKAN_LOG_DIR

Log directory

Override the default runtime/logs directory used by file logging.

ex) /var/log/akan

AKAN_LOG_MAX_SIZE_MB

Log rotation size

Create the next sequence file when a process log reaches this size.

ex) 50

AKAN_LOG_MAX_FILES

Log retention

Keep this many rotated files per process key, such as gateway or child-0.

ex) 100

AKAN_PUBLIC_ENV modes

local

My machine, my test data.

debug

Shared test data for reproduction.

develop

Team integration checks.

main

Production-like behavior.

AKAN_PUBLIC_OPERATION_MODE modes

local

Client talks to local runtime.

cloud

Client talks to cloud services.

edge

Client uses edge-facing paths.

Common setup scenarios

Build a feature locally

Reproduce with shared test data

Deploy production to cloud server

Deploy production to edge server

A common setup is ENV=local and OPERATION_MODE=local while building features, then switching ENV to debug or develop when you need to test with shared data or shared services.

getEnv()

getEnv() is the runtime helper that turns .env values into the information your app actually uses. Instead of hand-writing API URLs or WebSocket URLs, app code can read the prepared values from getEnv().

Using getEnv()

Local mode

When OPERATION_MODE is local, getEnv() points the browser and API client to your local Akan runtime, usually localhost:8282.

local

Cloud / edge mode

When OPERATION_MODE is cloud or edge, getEnv() builds service URLs from the app name, environment, and serve domain.

cloud / edge

Use getEnv() when application code needs runtime addresses or environment identity. It keeps URL decisions in one place and makes local, cloud, and edge modes easier to switch.

Health, Metrics, Logs

Akan runtime exposes simple ways to check whether the app is alive, how busy it is, and what it is doing. In local development, these are mostly useful when a page does not load or a background job seems stuck.

Health

Use this to check whether the gateway and server processes are running and ready.

health

Metrics

Use this to see runtime counts such as active requests, WebSocket connections, rooms, and process metrics.

metrics

Logs

Use AKAN_PUBLIC_LOG_LEVEL to choose how much detail appears in the terminal. AkanApp also stores gateway and child process output in runtime/logs by default, using AKAN_LOG_FILE_LEVEL for structured Logger output and rotating files by date and size.

logs

File names include app name, environment, operation mode, local date, process key, and sequence. Direct console.log calls from child servers are captured through stdout/stderr pipes; direct gateway console.log calls are not part of Logger sink capture.

Runtime checks

Start with health when the app does not respond. Use metrics when the app responds but feels busy. Increase LOG_LEVEL or enable AKAN_MEMORY_LOG when you need more terminal detail.

Akan Runtime

Root-level Env Variables

getEnv()

Health, Metrics, Logs

Relate Data

File Based Routing