An async PostgreSQL backend framework that generates REST APIs and authorized MCP tools from the same model and policy boundary.
Aksara is a PostgreSQL-backed Python application framework with generated APIs, shared authorization boundaries, and durable actions that recheck authority before supported effects.
It is for backend engineers building tenant-aware applications such as support desks, internal operations tools and SaaS APIs. Start with ordinary models and REST endpoints; agents can become clients later. You operate the Python service and PostgreSQL yourself.
FastAPI supplies typed HTTP endpoints, validation and dependency injection. Aksara adds an opinionated ORM/migration path, generated model APIs, application policy and tenant enforcement, and opt-in durable execution. Choose it when that shared contract is useful enough to justify adopting its data model.
The distinctive use case is an action that waits, retries, or outlives its
worker: current authority must still permit the mutation when it eventually
runs. With postgres_atomic, supported application changes and authoritative
Operation success commit in the same PostgreSQL transaction. External effects
have a separate reconciliation contract; no unconditional exactly-once promise
is made.
Aksara is pre-1.0. The backend and durable contracts are bounded and tested; planners, autonomous workflows, provider quality, memory and Studio internals remain experimental. Applications supply credential verification and business policy. Ordinary tasks do not automatically preserve a complete Principal. Read the v0.7 stability contract for the required production profile and exclusions.
Build a protected ticket API using a disposable PostgreSQL database:
python -m venv .venv
source .venv/bin/activate
python -m pip install "aksara-framework==0.7.2"
aksara startproject ticket_desk
cd ticket_desk
aksara dbsetupContinue with First project: a ticket desk for the complete model, routes, local authentication adapter, migrations, curl calls and standard-library API tests. The guide uses the installed package and keeps MCP, AI and Studio out of the initial application path.
aksara doctor launch-check diagnoses the local project. Production requires
separate role, tenant and operating checks; see the
deployment guide.
The two MCP-related paths have different meanings:
| Path | Purpose |
|---|---|
/mcp/ |
MCP Streamable HTTP protocol endpoint used by official clients |
/ai/tools/mcp |
Permission-filtered HTTP JSON inspection catalog of generated tool metadata |
MCP requires trusted server-side authentication that resolves the bearer
credential into a Principal; enabling the route does not verify credentials
for your application. Follow the
complete MCP quickstart
for the copy-pasteable model → migration → REST → Principal → official client →
persisted invocation path.
| Classification | Surface |
|---|---|
| Stable v0.6 | Async PostgreSQL ORM, relations and migrations |
| Stable v0.6 | Generated REST CRUD, validation, filters and pagination |
| Stable v0.6 | Principal, permissions, PolicyEngine, tenant and field enforcement |
| Stable v0.6 | MCP Streamable HTTP, generated tools, approval boundary, audit events, structured failures and runtime limits |
| Stable v0.6 | Core CLI, Doctor production policy, and PostgreSQL task queue |
| Stable v0.7 | Opt-in durable Operations, Attempts, idempotency, fencing, current reauthorization, decisions, retention, and external-effect recovery |
| Functional but evolving | Admin details, storage backends, email, search, SDK generation and DurableStep |
| Experimental | Studio/Studio AI, planners, prompt providers, investigation sessions, code patches, memory and autonomous workflows |
Application approval workflow UX, durable compliance retention, and external exactly-once effects remain application-owned. Protocol-level durable MCP Tasks are deferred because the official SDK does not yet implement the current Tasks extension; synchronous MCP tools remain unchanged.
Applications verify credentials and resolve a server-owned Principal. Aksara
then applies covered permission, object, policy, field, tenant, ORM transaction,
and RLS checks to REST and MCP execution. Schemas and hidden UI controls are
helpful descriptions; they are not authorization controls.
For production:
aksara doctor security-check
aksara doctor production-check --releaseRead the Security Overview and Production Hardening guide. Release gates and security tests provide repository evidence; they are not an external audit or certification.
The global aksara.conf.settings object is the runtime source of truth. Use
environment variables for deploy-time values and configure(...) for explicit
Python overrides. Precedence is explicit configuration, AKSARA_* environment
variables, supported aliases such as DATABASE_URL, then defaults.
DATABASE_URL=postgresql://user:password@localhost:5432/opsdesk
AKSARA_DEBUG=true
AKSARA_MCP_ENABLED=false
AKSARA_AI_ENABLED=false
AKSARA_ENABLE_STUDIO=falseAn AKSARA = {...} dictionary does not configure the runtime. See the
Settings Reference.
Studio is an experimental inspection and AI surface at /studio/ui. It is
disabled in new projects. Enabling it requires its secret/authentication and
production exposure settings; see the
Studio guide.
Provider-backed prompt execution is optional and experimental. Configure the current AI Hub path when you need it:
aksara ai-hub configure openai
aksara ai-hub status
aksara ai-hub doctorThere is no public AgentRuntime or Planner class. The documented
real primitives remain experimental and are described in the
AI Mode guide.
Set AKSARA_MCP_ENABLED=true only after adding server-side Principal
resolution, then connect an official MCP client to
http://127.0.0.1:8000/mcp/. MCP does not require an AI model provider.
From a source checkout, validate bundled examples with:
aksara examples validate --format json- Installation
- First Project
- MCP Quickstart
- Durable Authorized Operations
- v0.7 Stability Contract
- ORM
- API
- Security
- CLI
- Runtime compatibility
v0.7.0 implements the accepted Durable Authorized Operations architecture while preserving the v0.6 synchronous surfaces and PostgreSQL-first deployment profile. See the Roadmap.
Read the Contributing Guide and Code of Conduct. Run the relevant tests and strict documentation build before opening a pull request.