# Mainport at https://main.jmnet.one

This server runs **Mainport**: a self-hosted platform for its owner's own services and apps. It runs them,
deploys their releases, gives them hostnames and certificates, shows each one as an app inside Mainport (with
widgets on the home page and pages of its own), sends their notifications to the owner's phone, runs Claude for
them, and lets AI assistants work with all of it under permissions the owner approves. This page is public and
names nothing on the server; the details need a connection.

## If you're an AI assistant (Claude) reading this

1. **Already connected?** If the `mainport` command exists here, run `mainport sessions`. A connection listed there
   with a code is yours to use as `mainport --as <code> …` (in Claude Code, `/mp-me` says which one is this session's).
2. **Not connected:** ask the user for an invite (in Mainport: **Access → Connect an assistant**). The invite link
   is a guide of its own: it installs the helper from `https://main.jmnet.one/connect/mainport` and connects with a code the
   user approves. Without an invite, `https://main.jmnet.one/connect` explains the steps.
3. **See what's here:** run `mainport --as <code> discover`. It lists every service, its API, what you may use now,
   and what you could ask the user for (`mainport request <permission> --reason "…"`).
4. **Then do what the user asked.** If they didn't say, offer the few things that fit what you found, and don't
   guess at services or endpoints that aren't in that list.

## Building an app for Mainport

If the owner gave you this page along with a request to build something, they want it built **as a Mainport app**:
a service that runs on this server and lives inside Mainport. Unless they say otherwise:

1. **Start from the example.** `https://main.jmnet.one/discover/example-app.zip` is a complete small app (ASP.NET Core): the
   service, its manifests, a page, and `build.sh`, which makes the release zip. `https://main.jmnet.one/discover/apps.md` is
   the full reference for widgets, pages, the page SDK, Claude and notifications.
2. **Build it to the contract below and run it locally** until it works. You don't need a connection for that.
3. **When it works, put it on Mainport** (the owner expects that; don't stop at "it builds"):
   - Ask the owner for an invite and connect with what the job needs:
     `mainport login <invite> --name "Claude (<machine>)" --note "Build and deploy <app>" --permissions read,create`.
     `create` lets you make new services and deploy the ones you made, nothing else.
   - Create the service (the slug is its id: lowercase letters, digits, dashes):
     `mainport --as <code> api POST /api/services -H 'Content-Type: application/json' -d '{"name":"Hello","slug":"hello","description":"One line","healthPath":"/health"}'`.
     Leave `hostnames` out unless the app needs a public website of its own: inside Mainport it needs none.
     Ask the owner before giving it a public hostname.
   - Deploy: `mainport --as <code> deploy hello publish/hello.zip --version 1.0.0 --title "First release" --notes-file notes.md`.
     The notes are its changelog; write them for the owner, in plain words.
   - Check it runs (`mainport --as <code> api GET /api/services/hello`: state `Running`, healthy), then tell the
     owner where it is: **Mainport → its tile**, or `https://main.jmnet.one/#/apps/hello`.
4. **Later releases:** the same `deploy` with a higher version. Mainport keeps earlier releases for a rollback.

### The contract

- **A release is a zip** of the published program, with everything it needs at the root. Mainport finds the program
  itself: a .NET app's `.dll` or app host next to its `*.runtimeconfig.json`, or the one executable file. The
  server is Linux x64 with the .NET 10 runtime, so .NET apps can be framework-dependent; anything else must be a
  self-contained Linux x64 executable.
- **Listen where Mainport says:** `PORT`, and `ASPNETCORE_URLS` for .NET, on loopback. Mainport's proxy brings
  HTTPS traffic to it and sets the usual forwarded headers (`ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` is set).
- **Keep data in `MAINPORT_DATA_DIR`.** It survives every release; the release folder is replaced on each deploy.
  SQLite in the data folder is the usual choice.
- **Answer `GET /health`** with 200 when it's fine. Mainport checks it and shows the result.
- **Settings and secrets** are environment variables the owner sets in Mainport, never files in the release.
  Mainport also sets `MAINPORT_SERVICE` (the slug), `MAINPORT_RELEASE`, `MAINPORT_API` (Mainport's address for
  the service, on loopback), `MAINPORT_GATEWAY_SECRET`, and for a sandboxed service `MAINPORT_SOCKET`.
- **Logs** are stdout and stderr. Never log what users write, tokens or passwords.
- **Its routes for Mainport** go under `/mainport/` and must refuse any call without `X-Mainport-Gateway-Secret`
  equal to `MAINPORT_GATEWAY_SECRET` (compare in constant time). Mainport hides them from the public anyway.

### Its app inside Mainport

A `mainport-app.json` in the release makes the service an app: a tile on the home page and a page of its own.

- **Widgets** (most apps need little else): `stats`, `list`, `table`, `status`, `chart`, `markdown`, `actions`
  (buttons), `form` (settings) and `compose` (a message box). Mainport draws them in its own style from JSON your
  `/mainport/…` routes return.
- **Pages** for anything more: your own HTML in `mainport-ui/`, shown inside Mainport in a sandboxed frame. They
  talk to your app only through the SDK (`/app-sdk/mainport.js`: `Mainport.get/post/…`, `toast`, `confirm`,
  `navigate`, `setNav`, `setTitle`, `prefs`, `cache`) and take Mainport's look from `/app-sdk/mainport.css`.
- **Optional:** a `summary` line on the tile, a `changes` feed so everything updates live, `search` in Mainport's
  search bar, `webhooks`, an `oauthCallback` for signing in to other sites, and `claude` to have Mainport run
  Claude for the app (no Claude install or token of its own).
- **Notifications** to the owner's phone: `POST $MAINPORT_API/api/svc/push`. A phone app of its own (Android) is
  possible too; ask the owner first.
- **Assistants** reach an app's API only through routes it declares in `mainport-permissions.json`, each under a
  permission the owner grants.

### How a Mainport app should look and behave

The owner uses these on a phone as much as on a computer, and holds them to Mainport's own standard:

- **Mainport's look**, in light and dark: `mainport.css` and its classes (`card`, `row`, `stack`, `muted`, buttons,
  `pill`, `badge`, `stats`). No look of your own, no web fonts; the manifest's `color` is the accent.
- **Phone first.** Check every screen at 412×915 with touch, not only in a narrow desktop window. One setting per
  row, no squeezed columns, no button left alone on a line, and select arrows set in from the right edge.
- **Instant.** Every tap shows its effect at once (optimistic, undone if the call fails), and slow work runs in the
  background with a visible state. Pages draw from `Mainport.cache` first, then refresh.
- **Live.** Nothing waits for a reload or a slow timer: give the app a `changes` feed and redraw on `changed`.
- **Plain words.** Short labels and messages, written for the owner. Errors come back as `{ "error": "…" }` and
  Mainport shows them.
- **Widgets before pages**, and a full-screen page (`"fill": true`) only for things like a chat.

## What a connected assistant can do (with the owner's approval)

- Look at services: their status, logs, releases and changelog.
- Create services, and deploy new releases of a service or of Mainport itself.
- Use a service's own API through Mainport's gateway, permission by permission.
- Report a computer's Claude usage to Mainport (`mainport usage`).

Every permission is the owner's choice, can expire, and shows in Mainport's security log.