Apps

Last updated July 29, 2026Open markdown version

Apps are a customizable, interactive front end for your Tines workflows, and are fully supported on both cloud and self-hosted environments. This page focuses on the latter, so if you wish to learn more about Apps in general, see this page.

In self-hosted environments, the build process differs from Tines Cloud and introduces a small number of infrastructure requirements, most importantly an up-to-date tines-command-runner image and outbound access to an npm registry.

How app builds work on self-hosted

Every time an app's source files change, Tines bundles the app on the server: it resolves the app's npm dependencies, compiles the TypeScript and React source with esbuild, and stores the resulting JavaScript bundle for the app to render.

On Tines Cloud, that bundling runs in AWS Lambda. On self-hosted there is no Lambda, so bundling runs in tines-command-runner, the same container that already powers Run Script actions. The web server and background workers call tines-command-runner over HTTP on port 4400, the same connection already required for Run Script.

Each app gets its own build workspace on the tines-command-runner container's disk, holding its node_modules directory. The first build for an app is a cold build and runs a full npm install, which can take up to two minutes. Later builds reuse the cached dependencies and typically complete in a few seconds. When an app is deleted, Tines removes its workspace.

Requirements

Keep tines-command-runner aligned with your Tines version

The app build toolchain, Node and esbuild, ships inside the tines-command-runner image. The Tines UI exposes the app builder as soon as apps are enabled for your tenant, based on the entitlement alone. It does not check whether your tines-command-runner image can actually build. If you enable apps or upgrade tines-app without also re-pulling tines-command-runner, users will see the app builder and every build will fail.

Always upgrade tines-command-runner to the same version as tines-app. This is the same guidance that already applies to other command runner features, see Upgrading Tines.

No configuration is needed to turn the toolchain on; it is present in all official Tines images. If you build your own custom tines-command-runner images, you must pass the ENABLE_APPS_BUILD=1 Docker build argument, which defaults to off.

Connectivity

App builds add one outbound requirement to tines-command-runner.

No other connectivity changes are needed. Builds travel over the existing web server and background worker connection to the command runner on port 4400, and published apps are served from your existing tenant domain through your load balancer. For the full picture, see Connectivity requirements.

Resources

Plan for:

Disk headroom on the command runner. Each app keeps its own node_modules directory, plus a shared npm cache. Budget a few hundred megabytes per actively built app.
Ephemeral storage. Build workspaces live on the container's local disk and are not persisted across restarts. Losing them is safe, the next build simply repeats the cold npm install.
Cold builds after a restart or scale-out. If you run more than one tines-command-runner container, each keeps its own dependency cache, so the same app may build cold more than once. No session stickiness configuration is required for Apps.

Setting up Apps on self-hosted

Ask Tines to enable the apps entitlement for your tenant. Contact your Account Executive or Customer Success Manager, see Before you begin. Apps are gated by a tenant entitlement that cannot be self-enabled.
Confirm your tines-command-runner image matches your Tines version. See "Keep tines-command-runner aligned with your Tines version" above.
Confirm the command runner can reach an npm registry, either the public registry or an internal mirror.
Turn apps on for your tenant. As a tenant owner, go to https://your-tenant-domain/settings/apps. You can enable apps tenant-wide or for specific teams. See Admin settings for Apps.

Configuring the npm registry

By default, app builds fetch dependencies from the public npm registry. To use an internal mirror or private registry instead, set these environment variables on the tines-command-runner container. These sit alongside the Python package index settings documented in Run Script (tines-command-runner).

NPM_CONFIG_REGISTRY - URL of the npm registry used when building apps, for example an internal mirror. When unset, the public npm registry is used. Example: https://npm.your-company.com/
NPM_TOKEN - Auth token for a private npm registry. Has no effect unless NPM_CONFIG_REGISTRY is also set. The token is resolved from the environment at install time and is never written to disk.
NPM_CONFIG_STRICT_SSL - Set to false to disable TLS certificate verification for the npm registry. Prefer adding your registry's CA to the container using NODE_EXTRA_CA_CERTS; use this only as a last resort when the registry is behind a self-signed certificate you cannot otherwise trust.

You can also tune build behavior, though the defaults suit most deployments.

TCR_APPS_BUILD_TIMEOUT_SECONDS - Wall-clock limit for a single app build, in seconds. Default: 120
TCR_APPS_WORKSPACE_DIR - Directory holding per-app build workspaces. Default: /run/tcr/apps
TCR_APPS_NPM_CACHE_DIR - Shared npm cache directory. Default: /run/tcr/apps-npm-cache

Air-gapped and restricted-egress deployments

Because every build resolves dependencies at build time, apps cannot be built in an air-gapped deployment without an npm mirror. If your command runner has no route to a registry, point it at an internal mirror using NPM_CONFIG_REGISTRY. This is a current limitation of Apps on self-hosted.

How published apps are served

On Tines Cloud, published apps are served from a dedicated *.tines.app domain. On self-hosted they are served from your own tenant domain, at https://your-tenant-domain/apps/<app>.

Nothing extra is needed to support this. Apps reach your users over the same load balancer, TLS certificate, and hostname as the rest of Tines, so no additional DNS records or certificates are required. Viewers must be signed in to your Tines tenant, and access follows the app's visibility setting.