🌌 Akasa: Application Kernel & Volume Router
Akasa (Sanskrit for Ether / Substrate / Space) is a local-first, event-sourced Python micro-kernel.
Extracted from the inSetu Developer OS, Akasa acts as the foundational substrate for multi-tenant, offline-first Python applications. It is strictly domain-agnostic: it knows nothing about your application's business logic, acting purely as a high-performance routing and synchronization engine.
Status: beta (
0.x). Akasa powers inSetu in daily use, but its public API can still change between minor versions. Pin an exact version in your host application.
✨ Core Mechanics
- The Volume Router (VFS): An asynchronous, non-blocking Virtual File System. It abstracts physical disk I/O behind a strict Mount Table, allowing host applications to mount sandboxed repositories and virtual domains to unified URIs (e.g.,
vfs://orctx://). Writes go through a per-workspace commit queue;sync_vfs_barrier()waits for it to drain. - Stateless Multi-Tenancy: All databases, caches, settings, and file resolutions are scoped to an active
workspace_id, allowing a single daemon process to serve multiple isolated tenant environments safely. The active tenant travels with each call in anExecutionFrame(HTTP, IPC, worker, or CLI). - The Typed Event Bus: A synchronous/asynchronous
HookRegistryenforcing strict authorization boundaries for inter-module communication. Disabled extensions never receive events. - The Metronome (Worker Engine): A background SQLite-backed job ledger (
jobsandimmediate_jobs) providing recurring, one-shot, and DAG-chained task execution with progress telemetry, without blocking the request thread. - SQLite WAL Connection Pooling: Thread-local, auto-evicting database connection pooling explicitly optimized for Write-Ahead Logging concurrency, with declarative per-extension schemas and automatic column migrations.
- Scoped Settings & Secrets: A schema-driven
SettingsManagerwithdaemon,workspace,repo, andsecurescopes. Secure values are Fernet-encrypted insecrets.jsonunder a master key kept outside the workspace. - Capability Registry: Every extension route is also registered as a named capability (
<extension>.<action>) with its request/responseTypedDictschemas, so the same handler can be called over HTTP or in-process viactx.call(), and hosts can export the registry as OpenAPI or MCP tool descriptions. - Authentication & Peer Trust: A per-process session token gate, a three-route token exchange (
/auth/bootstrap), fail-closed reverse-proxy detection, and Host validation against DNS rebinding. See Security Model.
🏗️ Architecture Mandate
Akasa adheres to the Blind Substrate Mandate.
- Zero Domain Logic: Akasa does not parse target repositories, compile RAG contexts, or understand Git diffs. It only provides the tools to store and route them.
- Inversion of Control: All application-specific behavior is injected into Akasa by the host application via
@hooks.on()subscriptions, Driver registrations, and Volume mounts.
The Ring Structure
Kernel modules are layered in rings. A module may import from its own ring or any lower ring, never upward. The rule is enforced by the AST fitness suite (KERNEL_RING_DAG_MANDATE), so the layering cannot drift silently.
| Ring | Modules | Responsibility |
|---|---|---|
| 0 | types, uri, context |
Pure standard-library primitives: execution frames, URI parsing, atomic writes, template interpolation. |
| 1 | events, hooks |
The event bus, hook authorization, and the server-sent events (SSE) channel. |
| 2 | db, vfs, state, utils |
Persistence: SQLite pooling and migrations, the VFS and write queue, workspace configuration. |
| 3 | process, workers, sync |
Execution: sandboxed subprocesses, the Metronome job engine, state heartbeats. |
| 4 | auth, extension, akasa/__init__.py |
Transport and SDK: Flask wiring, authentication, the AkasaExtension blueprint, and the two-phase bootloader. |
Flask is confined to Ring 4 (KERNEL_TRANSPORT_ISOLATION), so Rings 0 through 3 run headless in CLIs, workers, and tests.
🚀 Installation
Akasa is designed to be installed as a foundational dependency for your host application. It requires Python 3.10+.
pip install akasa
⚡ Quick Start
A host application configures the kernel, declares extensions, and wires the Flask transport:
from flask import Flask
import akasa
from akasa.extension import AkasaExtension
# Phase A: process physics (no Flask needed; safe in CLIs and workers)
akasa.configure(control_dir=".myapp", extension_namespaces=["myapp.extensions."])
# An extension: routes, hooks, and workers share one tenant-scoped context
notes = AkasaExtension("notes", __name__, settings_schema=[
{"id": "greeting", "label": "Greeting", "type": "text", "scope": "workspace", "default": "hello"},
])
@notes.route("greet", methods=["GET"], docstring="[sync] Returns the configured greeting.")
def greet(ctx):
return {"workspace": ctx.workspace_id, "greeting": ctx.settings.get("greeting")}
@notes.on("note_saved")
def index_note(ctx, path=None, workspace_id=None, **kwargs):
ctx.jobs.submit("reindex", path=path)
@notes.worker("reindex")
def reindex(ctx, path: str = "", job_id: str = None):
ctx.jobs.update_progress(f"Indexed {path}")
# Phase B: wire the Flask transport (token gate, Host validation, DB teardown)
app = Flask(__name__)
akasa.init_app(app)
app.register_blueprint(notes.bp)
if __name__ == "__main__":
akasa.boot()
app.run(host="127.0.0.1", port=5005)
Extensions are opt-in per workspace. Enable notes in the workspace configuration (.myapp/config.json):
{
"extensions": ["notes"]
}
The route is served at /api/<workspace_id>/notes/greet and is registered as the capability notes.greet. Any other extension can call it in-process with ctx.call("notes.greet").
🔐 Security Model
Akasa assumes a single trusted user per daemon. An authenticated session holds the daemon's full authority, so treat the session token like a shell login.
- Session token: Every request except
/auth/bootstrapand any routes you declare public must carry the per-process token (headerX-Akasa-Tokenby default). The token is generated at startup, or taken fromAKASA_BOOT_TOKEN. - Token exchange (
/auth/bootstrap): Three routes, tried in order:- Localhost: an unproxied loopback connection that names a loopback Host (and, when present, a loopback Origin and Referer).
- Identity hook: host-provided handlers on
execute_identity_handshakereceive the classified peer and may vouch for it (inSetu uses this for Tailscale identity). - Static token: the
auth_tokenfrom the workspace configuration.
- Fail-closed proxy detection:
classify_peer()treats any forwarding header (Forwarded,X-Forwarded-*,X-Real-IP, or one the host registers) as proxied, so a proxy can never inherit localhost trust. Only the rightmostX-Forwarded-Forhop is trusted as the client address. Host code must not read these headers itself (FORWARDED_HEADER_MEMBRANE). - Host validation: Requests whose Host is not loopback, a registered trusted suffix, or an explicitly allowed hostname are rejected with
421 Misdirected Request, which blocks DNS-rebinding attacks. - Secrets: Secure settings are encrypted at rest with Fernet. The master key lives in
~/<control_dir>/master_key.txt, outside the workspace, and can be rotated.
🧪 Development & Testing
git clone https://github.com/Callosemic/akasa.git
cd akasa
pip install -e .
python tests/run_unit_tests.py # unit suite
python tests/fitness_functions.py # architectural fitness rules (ring DAG, transport isolation, ...)
The fitness suite statically checks the architecture: ring layering, Flask confinement, SQLite access only through db.py, VFS writes only through the write pipeline, zero host-domain leakage, and more. CI runs both suites together with sutram and inSetu, on Python 3.10 through 3.12.
akasa.reset_state() is the test-harness contract: it quiesces workers, drains the VFS queue, and resets every ring's state, so each test can run in its own sandbox.
📄 License
Licensed under the Apache License, Version 2.0. See the LICENSE and NOTICE files for details.
Metadata
Release files for akasa 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| akasa-0.6.0.tar.gz | 83.1 kB | Without provenance | Details for akasa-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| akasa-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for akasa-0.6.0-py3-none-any.whl |
Total release size: 169.6 kB
Release files / akasa-0.6.0.tar.gz
| Download URL | akasa-0.6.0.tar.gz |
|---|---|
| Size | 83.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8a2f76b3020df314443a55ef28ceacd7d46bb7aa5b091790ad62b7f9279a7e9
|
|
BLAKE2b-256 checksum How to use checksums |
1109b4a8f60ff879b0a39081dd9d97a0fde08f1fd19879af9839f8d4cb1257cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / akasa-0.6.0-py3-none-any.whl
| Download URL | akasa-0.6.0-py3-none-any.whl |
|---|---|
| Size | 86.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e1acebc17504d5eca09a1b3cbb65d4e49a30d2097d2e1d34a17734e9f1c476ad
|
|
BLAKE2b-256 checksum How to use checksums |
7b9e87038aba21fc778e6bbaffc27c4aef5275cf0e8463ffbdbdb84b02826345
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for akasa 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.