Run402 Core

Run402 Core is the open-source, self-hostable server and runtime core for
Run402 — backend infrastructure for AI agents. Run402 gives an
agent a Postgres database, user auth, file storage, serverless functions and site
hosting that it provisions and operates itself; this repository is the part of that
backend you can run on your own machine, under Apache-2.0. The agent-facing SDK, CLI
and MCP server live in kychee-com/run402 (MIT).

The current Core runtime-kernel slice is an Apache-2.0 self-hosting runtime. It can create a local project, plan and commit a supported ReleaseSpec, run inline PostgreSQL migrations, serve PostgREST/RLS behavior, serve active-release static content, handle local storage objects and route manifests, execute trusted local functions including durable function runs and single-node schedule triggers, run a narrow Astro SSR target, and import verified portable project archives.

Run402's wider product model treats people and agents as first-class participants: each acts through its own principal and authenticator, while explicit authority determines what it may do. Core supports the sovereignty side of that model by making a concrete application-runtime slice inspectable and portable. It does not currently reproduce the managed Cloud control plane, its human/agent principal graph, or its complete attribution history.

What Is Here Today

• packages/functions - @run402/functions, the helper library for deployed Run402 functions.
• packages/release - @run402/release, the release manifest semantics package.
• packages/runtime-kernel - public Core runtime contracts and application services.
• apps/core-gateway - public Core gateway composition root.
• docker-compose.yml - local Core, Postgres, and PostgREST stack.
• fixtures/runtime-kernel-static-rest - canonical static + Postgres/RLS conformance fixture.
• fixtures/storage-routing-core - canonical storage + static routing conformance fixture.
• CI for clean install, lint, build, tests, tarball verification, boundary checks, Compose boot, and Core conformance.

What Is Not Here Yet

This repo is not a complete production self-hosted Run402 distribution. It does not include Cloud's principal and organization authority graph, human control-plane login, grants/delegates, Buzz control-plane lifecycle, complete action-time attribution history, fleet scheduling, Aurora operations, global routing, Cloud billing operations, managed abuse controls, managed backups, monitoring, compliance automation, TLS automation, HA, custom domains, arbitrary dependency installation, hostile multi-tenant code isolation, or Cloud import back into managed Run402.

The promise of this slice is smaller and concrete: the supported Core runtime path is public, buildable, testable, and suitable for Run402 Cloud to consume or verify directly.

Extraction Status

Run402 Core is an open-source ratchet. Public-safe, production-used runtime code moves here, and Run402 Cloud consumes the public package or verifies against the public implementation.

Run402 Cloud remains the managed service and the authority for its participant, organization, grant, deploy, lease, billing, and runtime records. Core reduces vendor-lock-in risk for the supported application-runtime slice; it does not open-source the full control plane or fleet operations.

Packages

@run402/functions

In-function helper library for Run402 serverless functions. It provides typed access to caller-context database queries, admin database queries, auth helpers, email, AI, storage assets, cache helpers, routed HTTP utilities, and webhook verification.

npm install @run402/functions

Most users do not install it manually for deployed functions because Run402 Cloud auto-bundles the package at deploy time. Installing it locally is useful for TypeScript autocomplete and tests.

@run402/release

Release manifest semantics package. It is the public source for ReleaseSpec schemas, canonicalization rules, digest identities, portable state shape, and compatibility policy.

npm install @run402/release

Current package scope:

@run402/runtime-kernel

Public Core runtime contracts, capability document, project services, and apply plan/commit services.

Current runtime-kernel scope:

Development

npm ci
npm run lint
npm run build
npm test
npm run test:functions:smoke
npm run test:release:smoke
npm run core:boundary
docker compose up -d --build core
npm run core:health
npm run core:conformance
CORE_CONFORMANCE_RESTART=1 npm run core:storage-routing
docker compose down -v

See docs/runtime-kernel/quickstart.md, docs/runtime-kernel/capabilities.md, docs/runtime-kernel/storage-routing.md, docs/runtime-kernel/portable-archives.md, docs/runtime-kernel/security-defaults.md, and docs/open-source-readiness.md.

For the full Docker-hosted Core Gateway verification path, see docs/runtime-kernel/docker-compose-howto.md.

For app-level portability evidence after a deploy, see docs/runtime-kernel/core-certification.md.

For the first generic AWS target, see docs/deployment/aws-ec2/README.md.

Cloud Vs Core

Run402 Cloud is the managed service. Run402 Core is the public runtime and release-semantics code that can move toward self-hosting and portability over time.

Run402 Cloud should be the easiest place to start, not the only place the supported application can run. This is a bounded portability promise, not a claim that Core already reproduces every Cloud identity, authority, billing, or operations capability.

See CLOUD_VS_CORE.md.

Security

Please report vulnerabilities privately. See SECURITY.md.

License

Apache License 2.0. See LICENSE.