Add an Application Portal entry

An Application Portal entry gives your app an address such as https://<nas>/myapp/. A user who opens it signs in to DSM and lands in your app’s window. You declare the entry in dsm-package.yaml. The installer asks for the alias. An administrator turns the entry on.

Only an app with the executor can have an entry: capabilities.rootOps or capabilities.delegate (see Capabilities). DSM removes the alias at uninstall but keeps serving it until its web server reloads, and only root can reload it. The executor does that during uninstall. An app without privileges never uses root, so it cannot declare portal.

Add it

synopkgland add portal

The app must already declare root-ops or delegate, or add one in the same call, for example synopkgland add delegate,portal. Otherwise the command fails with STANDALONE_PORTAL_REQUIRES_EXECUTOR. The command writes portal: {} to dsm-package.yaml. If your os_min_ver is lower than 7.1-42661, it raises it to that value and prints the change. If portal is already set, the command reports it as unchanged. You can combine it with other capabilities, for example synopkgland add portal,files.

You can also write the field yourself:

os_min_ver: 7.1-42661
portal:
  # optional; the default is the package name as a slug
  alias: myapp

Field	Rule
`portal`	`{}` or `{alias: <alias>}`. No other keys.
`alias`	1 to 64 characters: lowercase letters, digits and hyphens. It must not start or end with a hyphen, and it must not be reserved.
Default alias	The package name in lowercase. If that is reserved or not a valid alias, `app-` followed by 12 hexadecimal characters.
`os_min_ver`	`7.1-42661` or higher
Executor	`capabilities.rootOps` or `capabilities.delegate`

Reserved aliases: dsfile, indexdb, mobile, oauth, scripts, sharing, ssdp, synosdsjslib, synohdpack, webapi, webman, calendar, chatplus, contacts, drive, file, photo, sso, synologymeet.

check and build fail with STANDALONE_PORTAL_INVALID for a bad portal value STANDALONE_PORTAL_MIN_DSM when os_min_ver is too low, and STANDALONE_PORTAL_REQUIRES_EXECUTOR when the app has no executor. inspect reports an SPK with a portal and no executor as PORTAL_REQUIRES_EXECUTOR.

What the installer and administrator do

Step	Who	What happens
Install	Person installing	On DSM 7.2 and later, the installation wizard has an Alias field filled with the default alias. A value that breaks the alias rules stops the install. DSM 7.1 uses executor registration and has no alias wizard step.
Turn on	Administrator	Opens your app and applies the alias in the Application Portal panel. Another way is Control Panel > Login Portal > Applications.
Open	Any user with access	Opens `https://<nas>/<alias>/` and signs in to DSM.
Uninstall	Executor	After DSM removes the alias, the executor reloads DSM’s web server, so the address stops opening at once.

The installer’s answer is only the suggested alias. The entry stays off until an administrator applies an alias. An administrator can also turn it off with Turn off.

DSM 7.2 and later register the portal entry through the SPK resource. DSM 7.1 uses the approved executor to register it. For an app whose manifest targets DSM below 7.2, the CLI builds executor portal mode into both Go and bridge runtimes. In App settings, administrators can use Enable entry and Remove entry for Go apps and bridge apps written in Rust, Python or Node, whether installed on DSM 7.1 or 7.4. The bridge runtime exposes the fixed portal.register and portal.unregister routes in this mode. Apps targeting DSM 7.2 or later use DSM resource management. These operations require the declared portal capability and executor approval; obtaining a session token does not enable an entry.

When you remove the entry from its own Portal page, the App asks for confirmation because that page will stop being available. After removal, follow the on-screen steps: choose Open DSM desktop, launch the App there, then go to Settings → Application Portal → Enable entry. Keep the removal result open until you have read these steps.

Opening a portal window

Open the active alias on the same NAS host where you signed in to DSM. When a desktop SynoToken is available, the shared window wrapper uses it. Otherwise it requests the current session token with a same-origin GET webman/login.cgi?enable_syno_token=yes, relative to the portal prefix, before backend and DSM WebAPI calls. Concurrent calls share the request; the token stays in memory. The request has a five-second deadline and rejects redirects, invalid responses and invalid tokens.

The browser still needs a valid DSM session. API and executor requests require the cookie and SynoToken, and native authenticate.cgi validation preserves the browser’s original client address. Token retrieval does not bypass these checks. If it fails, the request follows the existing session error path; sign in to DSM again on the same host and reopen the app.

When DSM’s Application Portal banner visibly names the app, AppShell hides its duplicate brand. It also hides the default account footer while DSM’s account menu is visible. A custom sidebar-footer stays; a hidden, missing or unrecognized banner keeps the shell’s own controls.

Use it

The default Vue UI shows the Application Portal panel when portal is declared. In the plain UI, mount the panel yourself:

ctx.portal.mountPanel(document.getElementById('portal'))

ctx.portal exists only when dsm-package.yaml declares portal.

Call	Result
`status()`	`{state, alias?, url?, canManage, controlPanel, defaultAlias}`. `state` is `active`, `inactive` or `unavailable`.
`apply(alias)`	Sets the alias and returns the new status. Administrators only.
`disable()`	Turns the entry off and returns the new status. Administrators only.
`openControlPanel()`	Opens Login Portal > Applications in the Control Panel.
`mountPanel(element)`	Renders a ready-made panel with the link, the alias form and the error text.

Administrators read and change the alias through DSM. Other users read it through the backend method portal.status, which every signed-in user can call. Users who are not administrators see the link when the entry is active, and a note to ask an administrator when it is not.

Limits

Limit	Value
Minimum DSM	7.1-42661
Apps that can declare it	Apps with `rootOps` or `delegate`
Alias length	1 to 64 characters
Entries per app	1
Who can apply or turn off	DSM administrators
Panel languages	en, zh-TW, zh-CN, ja, ko, de, fr, es, it

Troubleshooting

Code	Cause	Fix
`portal_alias_invalid`	The alias is empty, too long, uses other characters, or starts or ends with a hyphen.	Use 1 to 64 lowercase letters, digits or hyphens.
`portal_alias_reserved`	The alias is in the reserved list.	Choose another alias.
`portal_alias_in_use`	Another app already uses the alias.	Choose another alias.
`admin_required`	A user who is not an administrator tried to apply or turn off the alias.	Ask an administrator.
`portal_unavailable`	DSM did not accept the change.	Try again, or use Control Panel > Login Portal > Applications.
`STANDALONE_PORTAL_INVALID`	`portal` is not `{}` or `{alias}`, or the alias is invalid.	Fix the manifest.
`STANDALONE_PORTAL_MIN_DSM`	`os_min_ver` is below `7.1-42661`.	Raise `os_min_ver`, or run `synopkgland add portal`.
`STANDALONE_PORTAL_REQUIRES_EXECUTOR`	The app has neither `rootOps` nor `delegate`.	Add `root-ops` or `delegate`, or remove `portal` and let an administrator set up a reverse proxy in DSM.
The address still opens after uninstall	The executor’s cleanup failed; the system log entry `synopkgland-executor` says why.	An administrator saves an alias in Control Panel > Login Portal > Applications, which reloads the web server, or restarts the NAS.

DSM can report that an alias is invalid (4100), reserved (4102) or in use (4103). The panel shows these as portal_alias_invalid, portal_alias_reserved and portal_alias_in_use. See Errors for the full list.

A container app has no executor and cannot declare an entry; integration.web.portal fails with CONTRACT_PORTAL_REQUIRES_EXECUTOR. See Container apps.