App configuration

Most apps with an index.html need no configuration. Add marina.json at the project root when you want to set initial app details, handle requests, or use Marina services.

marina.json

{
  "schema": 1,
  "name": "My App",
  "icon": "⛵"
}

Manifest fields

Field	Required	Description
`schema`	No	Manifest format. Use `1`.
`name`	No	Initial display name, up to 80 characters.
`icon`	No	Initial app icon as an emoji.
`entrypoint`	No	Request handler, relative to the project root.
`runtime`	No	Versioned Marina services and secret names required by this app version.
`egress`	No	Public HTTPS hosts this app version may call.
`connections`	No	Workspace connections and the operations this app version may call on each.
`jobs`	No	Background handlers and optional schedules for this app version.
`access`	No	Scopes that app keys for this app can carry. Requires `entrypoint`.

The name and icon initialize a newly created app. After creation, change display metadata in the Marina dashboard; later code deployments preserve it.

Browser output

A project containing index.html can deploy directly. Projects with a package.json and a build script are built before deployment. Marina recognizes browser output in dist, build, out, public, or .output/public when that directory contains index.html.

Handle requests

Declare an entrypoint when the app needs to handle requests or use Marina runtime services:

marina.json

{
  "schema": 1,
  "name": "Status API",
  "icon": "📡",
  "entrypoint": "src/app.ts"
}

The entrypoint exports the handler passed to defineApp. Declare only the services that version uses:

marina.json

{
  "schema": 1,
  "entrypoint": "src/app.ts",
  "runtime": {
    "storage": "v1",
    "db": "v1"
  }
}

Only declare services the app uses. Adding a service to an existing app may produce a proposed version that a workspace publisher must approve before it can become live. Workspace connections are declared with the exact connection id and the operations the version may call on each:

marina.json

{
  "schema": 1,
  "entrypoint": "src/app.ts",
  "runtime": { "storage": "v1" },
  "connections": {
    "mercury": [{ "connection": "evident", "capabilities": ["transactions.list"] }]
  }
}

See Using connections in apps for validation, approval, and the calling API. App-specific credentials and direct HTTPS calls use runtime.secrets and egress.hosts:

marina.json

{
  "schema": 1,
  "entrypoint": "src/app.ts",
  "runtime": { "secrets": ["PAYMENTS_API_KEY"] },
  "egress": { "hosts": ["api.payments.example"] }
}

Secret names and allowed hosts belong to the immutable app version. Adding either may require publisher approval. See Managed secrets and outbound HTTPS for the runtime API, host matching rules, and CLI commands. To let CI jobs and other callers without a browser use the app, declare the scopes their app keys can carry:

marina.json

{
  "schema": 1,
  "entrypoint": "src/app.ts",
  "access": {
    "scopes": {
      "builds:publish": "Upload artifacts and publish builds"
    }
  }
}

Object storage

Store files and JSON under an isolated application namespace.

Application database

Query managed SQL data and evolve its schema with deployment migrations.

Connections

Read your business systems through workspace connections.

Background jobs

Run durable work on a schedule or from a request.

AI

Generate text with managed models.

Temporary links

Open one route to a request without a browser session.

Secrets and egress

Store app credentials and call approved public HTTPS hosts.

Project linking

After the first successful deploy, the CLI writes .marina/project.json. This stable link tells future commands which Marina app the directory belongs to, even if its display name changes. Do not commit .marina/project.json. To target an app explicitly from an unlinked directory, pass --app <slug>.

Name precedence

When creating an app, the CLI chooses its name in this order:

--name
name in marina.json
name in package.json
The directory name

Get started

Guides

Platform services

Connections

Reference

App configuration

Manifest fields

Browser output

Handle requests

Object storage

Application database

Connections

Background jobs

AI

Temporary links

Secrets and egress

Project linking

Name precedence

​Manifest fields

​Browser output

​Handle requests

Object storage

Application database

Connections

Background jobs

AI

Temporary links

Secrets and egress

​Project linking

​Name precedence

Manifest fields

Browser output

Handle requests

Project linking

Name precedence