Adding an app that is not in the catalogue

A machine arrives with a set of tools on it. Anything else — a service of your own, a container, a dev server you want to reach from a browser — is a **registered app**: a name, a port, and optionally a command the machine keeps running for you.

The control is **Register app**, and it is in the advanced view only. Turn that on first: the gear at the top right, then **Detail**. The button is then on the **Apps** card, and again on the **Ports** card.

What the form asks for

• **Name** — lowercase letters, digits and hyphens, 1 to 31 characters. It becomes both the URL and the unit name, so it is not editable afterwards.
• **Port** — 1024 to 65535, and not one a bundled tool has reserved; the Ports card lists those. Your app is told its port as PORT in its environment.
• **Working directory** — must be inside your home directory. It defaults to ~/projects.
• **Command** — the program and its arguments. It is **not** run through a shell, so a pipe, an && or a $VARIABLE here is passed through as text. When you need shell, the command is bash -lc "…".
• **Description** — for you, on the row.
• **Start at boot** — see below. It is refused on an app with no command, because there is nothing to start.
• **Expose at /apps/<name>/** — see below.

Surviving a reboot

Tick **Start at boot**. The machine writes a systemd unit called vmbox-app-<name>.service and enables it, so the app comes up with the machine. Your registration is also kept in the machine's own state and the unit is rebuilt from it when the machine software starts — so an upgrade or a repair does not lose your app.

Without that tick the app is still registered, still has a route and can still be started from the dashboard, but a reboot leaves it stopped.

1. Turn on the advanced view, and press **Register app** on the Apps card.
2. Give it a name, the port it listens on, the directory it runs in, and the command.
3. Tick **Start at boot**, and tick the expose box if you want to reach it from a browser.
4. Save. A row appears on the Apps card with **Start** and **Stop** on it.
5. Reboot from the gear, and check the row comes back running. That is the only proof that matters.

Reaching it from a browser

**A port is not an address.** Everything on this machine binds to loopback, and the HTTPS gateway is the only public listener — so a server on 127.0.0.1:3000 answers curl on the machine and nothing at all from your laptop. Ticking the expose box is what routes it.

The address is always /apps/<name>/ on your machine's own name. You do not choose the path, and a registered app does not get a hostname of its own — that exists for some bundled tools and not for yours. The prefix is stripped before the request reaches your app and passed on as X-Forwarded-Prefix, so an app that builds absolute links has to be told it lives under that prefix. Nothing rewrites its HTML for it.

An app with no command at all is allowed, and then the registration is a mapping only: it routes the port, and starting, stopping and surviving a reboot are yours. That is the shape for something you run by hand, or in a container.

Docker

Docker is installed on every machine and you have root, so containers work the way they do anywhere. A container is not a registered app and the machine does not manage it — but the two combine: publish the container's port on loopback, then register an app on that same port with no command and the expose box ticked. The container's own restart policy is what brings it back after a reboot; the registration does not.

Secrets

The form refuses an environment entry whose name looks like a credential — anything containing KEY, SECRET, TOKEN, PASSWORD, PASSWD or CREDENTIAL. That is deliberate rather than fussy: a value typed here would be readable in the unit file. Put it in the environment file instead, which every registered app's unit already reads.

What a registered app does not get

All of these exist for the bundled tools, which is exactly why it is worth knowing they do not exist for yours:

• **Waking on a request.** A bundled tool that is stopped starts when you open it. A registered app does not — a stopped one answers with a page saying it is not answering, and you press Start.
• **Sleeping when idle.** Not expressible for a registered app.
• **A hostname of its own.** The path, and only the path.
• **Being told the machine's public name.** When a machine is renamed, the bundled tools that have to advertise their own URL are reconfigured and restarted. A registered app is not, so anything of yours that prints its own address needs updating by hand.
• **A settings gear, a readiness probe, an install log, or a memory limit you choose.** Every registered app runs under the same 2 GB ceiling and 1024-task limit.

There is no command line for this

There is no vmbox app add. The dashboard form is the only way to register one, and the file it writes is owned by root in a directory your account cannot read, so editing it is not an alternative route.

A systemd unit you write by hand in /etc/systemd/system will run — it is your machine and you have root — but the machine software will not see it, it gets no route through the gateway, and it does not appear in the Ports table. If you want it in the dashboard, register it.