Aksara

An async PostgreSQL backend framework that generates REST APIs and authorized MCP tools from the same model and policy boundary.

What is Aksara?

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.

Why Aksara?

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.

10-Minute Quickstart

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 dbsetup

Continue 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.

REST and MCP

The two MCP-related paths have different meanings:

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.

Core Features

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.

Security boundary

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 --release

Read the Security Overview and Production Hardening guide. Release gates and security tests provide repository evidence; they are not an external audit or certification.

Configuration

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=false

An AKSARA = {...} dictionary does not configure the runtime. See the Settings Reference.

Open Studio

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.

Use AI

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 doctor

There is no public AgentRuntime or Planner class. The documented real primitives remain experimental and are described in the AI Mode guide.

Use MCP

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.

Examples

• Basic app
• Blog
• CRM
• Multi-tenant app
• Support Desk production reference

From a source checkout, validate bundled examples with:

aksara examples validate --format json

Documentation

• Installation
• First Project
• MCP Quickstart
• Durable Authorized Operations
• v0.7 Stability Contract
• ORM
• API
• Security
• CLI
• Runtime compatibility

Roadmap

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.

Contributing

Read the Contributing Guide and Code of Conduct. Run the relevant tests and strict documentation build before opening a pull request.

License

MIT