Building Marina apps¶
Marina hosts independently released application packages behind authentication.
Frontends, Python backends and current revisions live in Postgres. Every application
uses marina release; restarting or deploying Marina updates the base runtime and
preserves each app's selected revision. Merging source does not release it or load its data.
Choose the application shape¶
Use a static package for a report and add a Python backend to serve API endpoints. Either can be a named app when it needs stable named routes, scheduled jobs or the Loom panel for asking an agent to work on the application. Naming adds capabilities to the same release mechanism.
Choose where to keep source based on whether you expect to change the app again:
- Expect future changes: check the source into
infra/marina/apps/<name>/so people and agents can review and maintain it. - No future changes expected: release an ad hoc app from any local directory without checking in its source. A finished report is one example.
Both store their released code in Postgres and use the same commands. Ad hoc apps remain available after release. Whether an agent or a person created an app does not change this choice. Naming is a separate capability decision.
The package format retains the filename applet.toml and UUID field applet_id
so existing released revisions remain valid. These spellings do not describe
a separate app type. Use marina apps for release history, access modes, data,
rollback and archive operations.
Ordinary apps have stable /a/<uuid>/ URLs on an isolated origin. Named apps such
as Echo and EvalDash retain /echo/ and /evaldash/ on Marina. Initial named registration
requires an operator. The app's data_url and job credentials need explicit base-runtime
configuration; uploaded packages cannot allocate infrastructure or grant themselves
new credentials.
Python backends are trusted plugins sharing Marina's dependencies, process, resources and service identity. Applications needing separate dependencies, credentials or failure isolation need their own service project under the infrastructure conventions.
Build and release¶
Start with infra/marina/examples/problem-set-app/ for Python/Postgres or
infra/marina/examples/vue-app/ for Vue. A package contains applet.toml,
dist/index.html, browser assets, and optional Python modules. Maintained source
declares its stable applet_id UUID and optional repository-relative
source_paths for shared build inputs in the same applet.toml.
uv run marina validate my-app
uv run marina release my-app --dry-run --json
uv run marina release my-app --local --json
Preview opens a disposable Postgres-backed local stack. Exercise the UI and API at the printed revision URL, then stop the stack with Ctrl-C. Production releases from maintained source default to a clean checkout at the current remote main:
uv run marina release-status my-app --json
uv run marina apps versions UUID --json
uv run marina release my-app --base-version CURRENT_VERSION --json
Add --allow-dirty to release branch or uncommitted source to the selected
server. This bypasses the Git checks and omits verified source metadata, so
release-status reports unrecorded from a clean checkout. Use --local for a disposable preview.
The first release uses --base-version 0. Each later release requires the inspected
current revision. Release builds from empty output, validates Python imports, runs
the application's migration and atomically selects the new package. Old frontend
assets and backend revisions remain available within the retention window. Failed
migrations roll back their database changes and leave the prior revision selected.
The stable UUID and existing access mode are preserved.
Ad hoc directories without a Git repository use the same command. Their first
release --base-version 0 returns a UUID; later releases supply --id UUID and
--base-version CURRENT_VERSION. If you later decide to maintain an ad hoc app,
check its source into infra/marina/apps/<name>/ and declare its existing UUID
as applet_id in applet.toml. Release further revisions to that same app.
release-status compares recorded source trees, distinguishes local edits, and
reports unrecorded for packages without provenance. Declared shared build inputs
are included in the comparison; installed runtime dependencies also affect behavior. Source checks are operator
safeguards; server authentication and version checks remain authoritative. Any
internal Marina user can update, change the access mode, roll back or archive an
existing application. Publisher identity records attribution without restricting
access. Initial named registration and host bindings still require an operator.
For source layouts, manifests, auth, runtime configuration and the first production handover, see the Marina reference.
Frontend and API¶
Use relative asset/API URLs in UUID apps. Vue/Vite packages use base: "./" and
hash routing so stable and versioned URLs both work. Bundle dependencies into
dist/; executable inline scripts and third-party script CDNs are blocked.
Named applications keep their existing router and API prefixes. They can consume shared browser components at build time, including navigation and the agent panel. Updating those components requires releasing the consuming app; the base runtime does not ship frontend code.
A Python factory returns an ASGI application, or marina.apps.registered_api(api)
for explicitly annotated MCP operations. The factory's services argument supplies the selected app UUID,
revision, name, data URL and a role-scoped engine(). Read authenticated identity
through rigging.server_auth.get_verified_identity().
An optional migrate(connection) receives the release transaction's SQLAlchemy
Connection. It must not commit independently. Keep migrations compatible with
retained revisions and running old requests/jobs. Shared extensions belong to base
provisioning. A Marina runtime restart never reruns application migrations.
Load and cache data¶
Choose the serving data path before building the backend:
- Keep mutable state, reusable catalogs, filter indexes and summaries in the application's Postgres schema. A process cache disappears on restart.
- Load remote datasets separately from serving. Read a bounded committed snapshot when useful; never scan buckets or rebuild a catalog in a backend factory.
- Run refreshes in an explicit loader or a released scheduled-job module. Base configuration controls runner capacity, schedule and allowed credentials.
- Key caches by source version and query, record freshness, and serialize competing refreshes in Postgres. Preserve the last complete snapshot on failure.
- Keep large payloads in object storage, small immutable reports in the package, and live telemetry fresh through source queries or short TTLs.
For small scalar datasets:
uv run marina apps table load UUID observations rows.parquet --url ORIGIN
uv run marina apps sql UUID 'SELECT * FROM observations LIMIT 20' --url ORIGIN
Omitting --url targets production. Use the printed origin/UUID while a local
preview runs. Loading without --replace appends. --replace drops the table before
separate inserts; a live catalog needs staged loading and an atomic selection.
See Atlas for a code release plus explicit catalog-load workflow.
Operate¶
MCP discovery, named routes, directory entries and agent configuration follow the selected Postgres revision without a restart. Jobs snapshot and materialize their released packages before execution; an in-flight job keeps its snapshot while the next execution selects newly released code.
uv run marina apps versions UUID --json
uv run marina apps rollback UUID RETAINED_REVISION
uv run marina apps archive UUID
Rollback explicitly selects a retained package; database migrations are not reversed. The registry retains the current revision and four other recent revisions. A runtime rollback must still support the active package APIs and dependency requirements.
Apps default to private. Public mode exposes GET/HEAD only on the public app origin and must contain only data and trusted handlers intended for unrestricted access. Named apps stay private. See the reference for mode changes, query limits, deployment gates and recovery.