README
¶
AMOS
AMOS is an open-source, self-hosted foundation for building and operating paid SaaS applications that people and AI agents can use.
Each application owner runs their own installation. AMOS supplies the shared account, workspace, billing, API and operational capabilities so developers can focus on their business features.
The intended developer experience
amos init
amos deploy
The interactive initializer and deployment commands are the target workflow. A config-driven local initializer is available below. The initializer will generate a Go application, default UI, GitHub Actions workflows and infrastructure as code. Deployment will bring the application online at its own domain.
AMOS owns identity, workspace, policy, audit, billing and API/MCP application capabilities. The business application owns its landing page and business routes on the same public domain. The default integrates business code into the Go application; a separate-service option will support other stacks. AMOS remains useful during external workflow-service outages.
Planned capabilities
- Personal and organization workspaces, invitations, roles and account administration.
- Email/password, magic links, social login, passkeys, enterprise OIDC and MFA.
- Flat-rate, seat-based and usage-based subscriptions through a provider abstraction, starting with Stripe.
- Web interfaces and APIs, with MCP generated from OpenAPI so independently operated agents can connect. Mobile, SMS and end-user CLI clients come later.
- AWS deployment with required Cloudflare integration, offering managed containers/database and a small virtual machine profile.
- Deployment, monitoring, backups, recovery, immutable release and upgrade profiles, and owner controlled bounded domain maintenance.
Application code and Pulumi infrastructure programs use Go. The default UI uses server-rendered HTML, HTMX and plain JavaScript/CSS, and is replaceable. AMOS enforces application authorization; external agents retain their own governance.
Implementation status
AMOS is under active development. It is not yet a complete runnable SaaS or a qualified production deployment.
Implemented foundations include real PostgreSQL test infrastructure and transactional migrations; configuration and policy validation; durable jobs and an outbox; email delivery and audit components; identity storage, sessions, password hashing, email verification and signup/sign-in components; workspace persistence, personal workspace bootstrap and request context; OpenAPI validation and Go code generation; a tenant-scoped reference todo service; the default UI renderer and protected template overrides; atomic initializer generation; and scoped billing intents and persistence.
The generated local application composes signup, explicit email verification, sign-in, a personal workspace, reference todos, password recovery and guarded TOTP services. The execution record currently accepts 57 of 257 planned tasks; this is a task count, not a completion percentage. Organization administration, complete subscription processing, deployment commands, cloud infrastructure, MCP, upgrades and operational recovery remain to be completed. Local generation is qualified only for the documented evaluation path; billing and production are not qualified. Local checks and provider fixtures do not qualify live services.
AMOS owns application identity, workspaces, policy, audit, billing and API/MCP boundaries. An external code-change lifecycle service owns PR safety and the executable author, independent review, bounded fix, re-review and landing tasks. A separate product workflow controller owns product delivery and qualification. AMOS may diagnose owner-local issues, generate proposals and upgrades, and run bounded domain jobs; it does not build a second task or PR orchestrator. Release and upgrade profiles are immutable and owner reviewed. Restricted implementation source is not copied into this public repository.
See the current roadmap and execution record for task-level progress.
Generate a local evaluation app
From this checkout, with the supported Go toolchain installed:
mkdir -p ../amos-apps
cat > initializer.json <<'JSON'
{
"schemaVersion": 1,
"appSlug": "todo-demo",
"module": "example.test/todo-demo",
"parentDir": "../amos-apps",
"target": "todo-demo",
"modules": ["identity", "workspace"],
"publicOrigin": "http://127.0.0.1:8080",
"businessMode": "integrated-go",
"mode": "evaluation"
}
JSON
go run ./cmd/amos init --config initializer.json --framework-source .
go build -o ../amos-apps/amos-dev ./cmd/amos
cd ../amos-apps/todo-demo
mkdir -p .amos/bin
go build -o .amos/bin/app ./cmd/app
../amos-dev dev --project todo-demo --dir . --binary .amos/bin/app
The native development runner requires running Podman and an available PostgreSQL
image. It reads the private generated configuration, migrates and starts the Go
server, and preserves its database volume when stopped. The alternative
./scripts/dev requires an installed Podman Compose provider. Missing prerequisites fail visibly. If the database
is already running on that port, use its explicitly configured migration and
runtime URLs with go run ./cmd/app migrate and go run ./cmd/app serve.
The database must be a disposable local evaluation database.
Visit http://127.0.0.1:8080/signup. Verification and reset messages are captured
in private .amos/mail files; open the message's confirmation link and submit
the confirmation form. Keep .amos and .env.local private and retain the
generated framework bundle. Owner business code is in app/business, UI in
ui, and reference business migrations in migrations.
This is a loopback evaluation installation. Local capture does not send live
email. The Compose scripts have not been qualified in the current environment
because its Compose provider is absent; the generated executable, real
PostgreSQL and Chromium lifecycle have been qualified directly. Billing and
production generation fail explicitly until their composition is available.
See generator evidence and
native runner evidence.
amos-dev status --project todo-demo --dir . inspects the local installation;
amos-dev clean --plan --project todo-demo --dir . is advisory only.
Development and architecture
- Development prerequisites
- Migration behavior
- Vision
- Architecture RFC
- Complete staged implementation plan
- Contributor/session resume guide
- AMSL reuse strategy
License
Original AMOS code is licensed under Apache 2.0. Third-party licenses and notices are preserved in THIRD_PARTY_NOTICES.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app exposes the composition seam used by generated AMOS applications.
|
Package app exposes the composition seam used by generated AMOS applications. |
|
operation
Package operation defines immutable typed operation descriptors and their startup registry.
|
Package operation defines immutable typed operation descriptors and their startup registry. |
|
operation/sqlstore
Package sqlstore persists operation claims in the caller's transaction.
|
Package sqlstore persists operation claims in the caller's transaction. |
|
Package apphost composes the shared runtime for generated applications.
|
Package apphost composes the shared runtime for generated applications. |
|
Package audit defines the bounded security-event contract used by trusted application services.
|
Package audit defines the bounded security-event contract used by trusted application services. |
|
sqlstore
Package sqlstore persists audit events.
|
Package sqlstore persists audit events. |
|
billing
|
|
|
catalog
Package catalog holds reviewed, server-side flat-price catalog versions and evaluates paid-feature access from fresh, scoped subscription projections.
|
Package catalog holds reviewed, server-side flat-price catalog versions and evaluates paid-feature access from fresh, scoped subscription projections. |
|
checkout
Package checkout exposes the authenticated workspace checkout boundary.
|
Package checkout exposes the authenticated workspace checkout boundary. |
|
personalmanage
Package personalmanage exposes the authenticated personal-workspace billing inspection and provider portal boundary.
|
Package personalmanage exposes the authenticated personal-workspace billing inspection and provider portal boundary. |
|
provider
Package provider defines the narrow boundary between AMOS billing policy and external payment providers.
|
Package provider defines the narrow boundary between AMOS billing policy and external payment providers. |
|
reconcile
Package reconcile durably schedules and applies current-provider billing snapshots.
|
Package reconcile durably schedules and applies current-provider billing snapshots. |
|
store
Package store persists workspace-scoped billing bindings and provider work.
|
Package store persists workspace-scoped billing bindings and provider work. |
|
stripecheckout
Package stripecheckout adapts Stripe's official Go SDK to AMOS's narrowly scoped customer and hosted Checkout contracts.
|
Package stripecheckout adapts Stripe's official Go SDK to AMOS's narrowly scoped customer and hosted Checkout contracts. |
|
webhook
Package webhook accepts Stripe events only after SDK signature verification and durable, scoped receipt.
|
Package webhook accepts Stripe events only after SDK signature verification and durable, scoped receipt. |
|
cmd
|
|
|
amos
command
|
|
|
amos-devtls
command
Command amos-devtls serves the reference personal application through the explicit development-only TLS profile.
|
Command amos-devtls serves the reference personal application through the explicit development-only TLS profile. |
|
portableplan
command
Command portableplan exports the AMOS authored plan as a read-only portable definition.
|
Command portableplan exports the AMOS authored plan as a read-only portable definition. |
|
delivery
|
|
|
email
Package email owns safe, bounded email intent rendering and delivery semantics.
|
Package email owns safe, bounded email intent rendering and delivery semantics. |
|
email/internal/invitationurl
Package invitationurl recognizes only the admitted invitation URL shape.
|
Package invitationurl recognizes only the admitted invitation URL shape. |
|
email/localcapture
Package localcapture is an explicitly unqualified local development mailbox.
|
Package localcapture is an explicitly unqualified local development mailbox. |
|
email/materialstore
Package materialstore encrypts short-lived email delivery material in the same PostgreSQL transaction as its identity challenge and outbox intent.
|
Package materialstore encrypts short-lived email delivery material in the same PostgreSQL transaction as its identity challenge and outbox intent. |
|
email/ses
Package ses sends AMOS email through Amazon SES API v2.
|
Package ses sends AMOS email through Amazon SES API v2. |
|
examples
|
|
|
continuity/domain
Package domain provides pure, application-owned continuity value rules.
|
Package domain provides pure, application-owned continuity value rules. |
|
continuity/guide
Package guide provides finite, application-owned continuity briefings.
|
Package guide provides finite, application-owned continuity briefings. |
|
continuity/host
Package host contains private composition components.
|
Package host contains private composition components. |
|
continuity/repository
Package repository stores continuity values in a caller-owned transaction.
|
Package repository stores continuity values in a caller-owned transaction. |
|
continuity/ui/baselineview
Package baselineview renders supplied continuity values.
|
Package baselineview renders supplied continuity values. |
|
continuity/ui/sourceview
Package sourceview renders bounded, caller-supplied source values.
|
Package sourceview renders bounded, caller-supplied source values. |
|
reference/app/business
Package business is the reference, tenant-scoped todo service.
|
Package business is the reference, tenant-scoped todo service. |
|
reference/app/business/apigen
Code generated by AMOS Go types generator v1; DO NOT EDIT.
|
Code generated by AMOS Go types generator v1; DO NOT EDIT. |
|
reference/migrations
Package migrations supplies the reference application's business fragment.
|
Package migrations supplies the reference application's business fragment. |
|
reference/ui
Package ui provides the server-rendered reference landing and todo pages.
|
Package ui provides the server-rendered reference landing and todo pages. |
|
ui-overrides
command
Example ui-overrides demonstrates composing selected owner templates with the shared server-rendered UI.
|
Example ui-overrides demonstrates composing selected owner templates with the shared server-rendered UI. |
|
email
Package email coordinates purpose-bound email verification.
|
Package email coordinates purpose-bound email verification. |
|
federation
Package federation binds verified provider identities to local people through browser-bound, one-use authorization callbacks.
|
Package federation binds verified provider identities to local people through browser-bound, one-use authorization callbacks. |
|
internal/authproof
Package authproof defines credential proof values available only to the identity subtree.
|
Package authproof defines credential proof values available only to the identity subtree. |
|
internal/organizationaction
Package organizationaction encodes finite organization intents.
|
Package organizationaction encodes finite organization intents. |
|
internal/organizationproof
Package organizationproof retains facts from one actual current-password verification.
|
Package organizationproof retains facts from one actual current-password verification. |
|
internal/passwordwork
Package passwordwork bounds native password computation independently of its caller's transaction lifetime.
|
Package passwordwork bounds native password computation independently of its caller's transaction lifetime. |
|
internal/writerproof
Package writerproof holds closed native identity evidence for one W1 attempt.
|
Package writerproof holds closed native identity evidence for one W1 attempt. |
|
issuer
Package issuer implements the finite personal authorization profile.
|
Package issuer implements the finite personal authorization profile. |
|
login
Package login implements public registration and email-password sign-in.
|
Package login implements public registration and email-password sign-in. |
|
magiclink
Package magiclink composes purpose-bound email proof with AMOS's durable identity and session stores.
|
Package magiclink composes purpose-bound email proof with AMOS's durable identity and session stores. |
|
mfa/vault
Package vault encrypts TOTP seed material for the MFA factor store.
|
Package vault encrypts TOTP seed material for the MFA factor store. |
|
organizationactions
Package organizationactions implements closed native organization actions.
|
Package organizationactions implements closed native organization actions. |
|
password
Package password wraps maintained Argon2id with bounded resource policy.
|
Package password wraps maintained Argon2id with bounded resource policy. |
|
password/policy
Package policy supplies a versioned, local common-password blocklist.
|
Package policy supplies a versioned, local common-password blocklist. |
|
primaryproof
Package primaryproof verifies the current primary password for factor enrollment and step-up.
|
Package primaryproof verifies the current primary password for factor enrollment and step-up. |
|
protection
Package protection enforces bounded authentication admission at HTTP boundaries.
|
Package protection enforces bounded authentication admission at HTTP boundaries. |
|
recovery
Package recovery implements purpose-bound password reset and authenticated password change.
|
Package recovery implements purpose-bound password reset and authenticated password change. |
|
session
Package session implements durable opaque browser sessions.
|
Package session implements durable opaque browser sessions. |
|
store
Package store persists AMOS identity state in an existing PostgreSQL transaction.
|
Package store persists AMOS identity state in an existing PostgreSQL transaction. |
|
infra
|
|
|
backupschedule
Package backupschedule declares owner-selected backup triggers.
|
Package backupschedule declares owner-selected backup triggers. |
|
internal
|
|
|
authoritywriter
Package authoritywriter provides the finite W1 transaction ordering protocol.
|
Package authoritywriter provides the finite W1 transaction ordering protocol. |
|
backup
Package backup creates consistency-aware PostgreSQL logical backups.
|
Package backup creates consistency-aware PostgreSQL logical backups. |
|
buildtrustcontract
Package buildtrustcontract validates the public, design-only release evidence shape and a caller-supplied trusted-builder policy.
|
Package buildtrustcontract validates the public, design-only release evidence shape and a caller-supplied trusted-builder policy. |
|
businessgen
Package businessgen generates typed business registration skeletons.
|
Package businessgen generates typed business registration skeletons. |
|
cli/generate
Package generate implements the command handler used by the root CLI.
|
Package generate implements the command handler used by the root CLI. |
|
codegen
Package codegen validates the AMOS OpenAPI contract and produces stable generation manifests.
|
Package codegen validates the AMOS OpenAPI contract and produces stable generation manifests. |
|
codegen/gotypes
Package gotypes emits typed Go API models and business handler interfaces from the validated AMOS OpenAPI contract.
|
Package gotypes emits typed Go API models and business handler interfaces from the validated AMOS OpenAPI contract. |
|
devrunner
Package devrunner supervises the generated application's local development process and only the PostgreSQL resources assigned to its project.
|
Package devrunner supervises the generated application's local development process and only the PostgreSQL resources assigned to its project. |
|
diagnosticcontract
Package diagnosticcontract checks the finite, design-only public diagnostic profile.
|
Package diagnosticcontract checks the finite, design-only public diagnostic profile. |
|
diagnosticsanitize
Package diagnosticsanitize constructs bounded local diagnostic previews from untrusted structured events.
|
Package diagnosticsanitize constructs bounded local diagnostic previews from untrusted structured events. |
|
doctor
Package doctor reports local prerequisites without changing the machine.
|
Package doctor reports local prerequisites without changing the machine. |
|
health
Package health provides bounded HTTP liveness and readiness handlers.
|
Package health provides bounded HTTP liveness and readiness handlers. |
|
initializer
Package initializer validates an application request and stages generated files in a resumable transaction before atomically publishing its directory.
|
Package initializer validates an application request and stages generated files in a resumable transaction before atomically publishing its directory. |
|
issuerbinding
Package issuerbinding carries private lookup data, never authorization proof.
|
Package issuerbinding carries private lookup data, never authorization proof. |
|
opsconfig
Package opsconfig defines owner supplied operational targets.
|
Package opsconfig defines owner supplied operational targets. |
|
ownership
Package ownership renders a bounded, data-only ownership manifest component.
|
Package ownership renders a bounded, data-only ownership manifest component. |
|
recoverykeys
Package recoverykeys owns the concrete recovery file provider and the private key-transfer bridge.
|
Package recoverykeys owns the concrete recovery file provider and the private key-transfer bridge. |
|
runtime
Package runtime composes the public AMOS HTTP route surface.
|
Package runtime composes the public AMOS HTTP route surface. |
|
scaffold/application
Package application generates the real, integrated-Go local reference app.
|
Package application generates the real, integrated-Go local reference app. |
|
scaffold/ci
Package ci defines the trust boundary for generated continuous integration.
|
Package ci defines the trust boundary for generated continuous integration. |
|
scaffold/local
Package local generates the Podman assets used by a developer's local environment.
|
Package local generates the Podman assets used by a developer's local environment. |
|
scaffold/ops
Package ops generates and evaluates finite, local-only operational alert definitions.
|
Package ops generates and evaluates finite, local-only operational alert definitions. |
|
securitycontract
Package securitycontract validates the public, design-only AMOS threat matrix.
|
Package securitycontract validates the public, design-only AMOS threat matrix. |
|
telemetry
Package telemetry provides privacy-preserving HTTP request logging.
|
Package telemetry provides privacy-preserving HTTP request logging. |
|
testkit
Package testkit provides isolated PostgreSQL databases for integration tests.
|
Package testkit provides isolated PostgreSQL databases for integration tests. |
|
upstreamconfig
Package upstreamconfig validates a declared upstream deployment design.
|
Package upstreamconfig validates a declared upstream deployment design. |
|
upstreamintake/payload
Package payload decodes bounded diagnostic payload bytes.
|
Package payload decodes bounded diagnostic payload bytes. |
|
vulnerabilityroute
Package vulnerabilityroute holds unreviewed assessments for qualified private handling.
|
Package vulnerabilityroute holds unreviewed assessments for qualified private handling. |
|
Package jobs defines bounded durable intent and consumer outcomes.
|
Package jobs defines bounded durable intent and consumer outcomes. |
|
sqlstore
Package sqlstore persists bounded jobs and their execution fencing in PostgreSQL.
|
Package sqlstore persists bounded jobs and their execution fencing in PostgreSQL. |
|
Package migrations defines the immutable, globally ordered migration registry.
|
Package migrations defines the immutable, globally ordered migration registry. |
|
Package objects stores short-lived, tenant-owned lifecycle exports without exposing provider keys or presigned URLs to callers.
|
Package objects stores short-lived, tenant-owned lifecycle exports without exposing provider keys or presigned URLs to callers. |
|
s3
Package s3 implements the private object store using the AWS SDK for Go v2.
|
Package s3 implements the private object store using the AWS SDK for Go v2. |
|
Package observability provides finite, process-local private operator metrics.
|
Package observability provides finite, process-local private operator metrics. |
|
Package policy defines the shared operation decision contract.
|
Package policy defines the shared operation decision contract. |
|
proxy
|
|
|
identity/sqlstore
Package sqlstore implements durable, bounded private-hop replay consumption.
|
Package sqlstore implements durable, bounded private-hop replay consumption. |
|
transport
Package transport implements a fixed-origin, private-address mutual-TLS transport.
|
Package transport implements a fixed-origin, private-address mutual-TLS transport. |
|
Package recovery exposes native identity backup production.
|
Package recovery exposes native identity backup production. |
|
filestore
Package filestore exposes the finite owner-provisioned local recovery-key provider.
|
Package filestore exposes the finite owner-provisioned local recovery-key provider. |
|
Package storage owns the PostgreSQL pool used by an AMOS application.
|
Package storage owns the PostgreSQL pool used by an AMOS application. |
|
ui
|
|
|
authpassword
Package authpassword renders the default browser password lifecycle.
|
Package authpassword renders the default browser password lifecycle. |
|
billingcheckout/testserver
command
|
|
|
overrides
Package overrides composes selected, owner-authored page templates and namespaced theme assets around the public ui/render contract.
|
Package overrides composes selected, owner-authored page templates and namespaced theme assets around the public ui/render contract. |
|
render
Package render provides the default escaped server-rendered page shell and the public seam used by applications that supply another renderer.
|
Package render provides the default escaped server-rendered page shell and the public seam used by applications that supply another renderer. |
|
render/testserver
command
Command testserver serves the real renderer to the browser shell spec.
|
Command testserver serves the real renderer to the browser shell spec. |
|
workspaceswitch
Package workspaceswitch renders and changes the browser's current workspace hint.
|
Package workspaceswitch renders and changes the browser's current workspace hint. |
|
workspace
|
|
|
context
Package context resolves an untrusted workspace selection against the authenticated person and current PostgreSQL state at each request boundary.
|
Package context resolves an untrusted workspace selection against the authenticated person and current PostgreSQL state at each request boundary. |
|
organizations
Package organizations implements the private native directory reader.
|
Package organizations implements the private native directory reader. |
|
personal
Package personal creates and repairs the single personal workspace bound to a verified person.
|
Package personal creates and repairs the single personal workspace bound to a verified person. |
|
store
Package store provides transaction-scoped PostgreSQL persistence for personal and organization workspaces.
|
Package store provides transaction-scoped PostgreSQL persistence for personal and organization workspaces. |
Click to show internal directories.
Click to hide internal directories.