App Runtime Environment
YouTrack apps run in two connected environments: the browser with the YouTrack frontend and the YouTrack backend. Frontend widgets run in sandboxed iframes and communicate with YouTrack through the Host API. Backend modules run in the apps backend runtime and use the JavaScript API to work with YouTrack entities, app data, and external services.
Use this page to identify where app code runs, which API handles each communication path, and where app data is stored.
The table below summarizes the main runtime blocks from the diagram.
Runtime area | Runtime contents | Communication interfaces | App data storage |
|---|---|---|---|
Browser and YouTrack frontend | Sandboxed widget iframes with app HTML, CSS, and JavaScript. | The Host API, including:
| Local browser storage that belongs to the app and browser client. |
YouTrack backend |
|
| YouTrack database records, including extension properties, app global storage, and app settings. |
Communication Paths
Choose the communication path based on the source and target of the request.
Request path | API or module | Purpose |
|---|---|---|
Widget to YouTrack REST API | Read or update YouTrack entities through REST API endpoints under | |
Widget to app backend | Call app-defined backend logic from a widget. | |
External service to app backend | Receive webhooks or expose custom app endpoints for third-party services. | |
Backend app module to external service |
| Send outbound HTTP requests from workflow rules, HTTP handlers, custom scripts, or custom MCP tools. |
Backend app module to YouTrack data | Backend JavaScript API | Read or update YouTrack entities and app-owned extension properties without a widget request. |
Browser and YouTrack Frontend
The YouTrack frontend provides an isolated browser environment where app widgets render their user interface. Frontend runtime responsibilities include widget HTML, CSS, JavaScript, frontend communication with YouTrack, and local browser storage.
Sandboxed iframe
Each app widget runs in a sandboxed iframe. The iframe uses the sandbox attribute to isolate its internal code from the host environment. YouTrack supplies this iframe with the Host API, which lets the widget communicate with the rest of the frontend and with the backend application.
This isolation has the following effects:
Widget HTML, CSS, and JavaScript don't directly affect the YouTrack frontend.
YouTrack frontend styles don't automatically apply to widget content.
Widget code uses the Host API instead of direct access to host application internals.
To give your custom views a consistent look and feel, we recommend building widgets with components from JetBrains' open-source Ring UI library.
This environment allows for extensive customization of the YouTrack UI, letting you add custom panels, controls, and views that enhance the user experience. These customizations can be accessed through predefined extension points. For a complete list and a description of each available extension point, see Extension Points for Widgets.
Host API
The Host API is the controlled communication layer between app widgets and YouTrack. App widgets use the Host API for YouTrack REST API requests, app backend requests, and local browser storage.
Host API member | Operation |
|---|---|
Send requests to YouTrack REST API endpoints under | |
Invoke custom app endpoints implemented by backend HTTP handlers. | |
Store app-owned string values locally in the browser. |
Frontend Data Storage
To minimize security risk and potential data loss, the frontend sandbox is not allowed direct access to client-side browser APIs like localStorage, sessionStorage, and web cookies.
To store frontend app data, use host.storage. This storage saves string values locally in the browser in a persistent storage area isolated for the app. All widgets from the same app share this local storage area.
Frontend storage data | Backend storage data |
|---|---|
Local UI state, draft text, and browser-side caches. | Data that must be available to backend scripts, other users, or the same user in another browser. |
Values that can remain local to one browser client. | Values that must be stored by YouTrack and protected by YouTrack permissions. |
YouTrack Backend
The YouTrack backend contains the REST API, apps backend runtime, and the persistence layer used by YouTrack entities and backend app data.
REST API
The REST API is the backend entry point for requests from app widgets and external clients. Requests sent with host.fetchYouTrack() call YouTrack REST API endpoints. Requests sent with host.fetchApp() call app endpoints that are routed through the REST API and invoke backend HTTP handlers.
The REST API applies the relevant app endpoint permissions and YouTrack entity permissions before requests reach backend app code or core YouTrack entities.
Apps Backend Runtime
The apps backend runtime is based on GraalJS, a JavaScript engine built on GraalVM. GraalJS provides interoperability between JavaScript backend modules in apps, including workflow rules, HTTP handlers, custom scripts, and custom MCP tools, and YouTrack internal functions and persistence layer, including YouTrack entities.
GraalJS runs app backend code in a sandboxed environment. The sandbox limits what backend JavaScript can do and helps keep app execution isolated and more secure.
The backend JavaScript API lets app modules read and update core entities, like issues and articles. It also lets an app read and store custom data in entity extensions, which provide a persistence layer for apps.
Backend module | Purpose |
|---|---|
Automate YouTrack behavior in response to events, manual actions, or schedules. | |
Add app-defined endpoints to the YouTrack REST API. | |
Expose app-defined tools through the YouTrack MCP server. | |
| Send outbound HTTP requests from backend app modules to external services. |
Workflow Rules
Workflow rules run in the backend runtime and let you extend and automate YouTrack behavior using JavaScript. They can interact with YouTrack entities in response to events, manual actions, or schedules.
To learn how to add a workflow rule to your app, see JavaScript Modules.
For help writing workflows in JavaScript, read our JavaScript Workflow Quick Start Guide.
HTTP Handlers
The apps backend runtime provides support for custom HTTP handlers. HTTP handlers extend the YouTrack REST API with app-defined endpoints that run in the backend runtime. App widgets can use these endpoints as a custom REST API for server-side app logic. External services can call them as webhooks or custom HTTP endpoints for automations and integrations.
For an example of an app that uses HTTP handlers as webhook endpoints, see Webhook Triggers.
For further information, see HTTP Handlers.
Custom MCP Tools
Custom MCP tools are backend app modules that expose app-defined tools through the YouTrack MCP server. Use them when an app needs to add AI-facing actions that work with YouTrack data or app-specific logic.
For further information, see Custom MCP Tools.
Outbound HTTP Requests
Backend modules can use the @jetbrains/youtrack-scripting-api/http module, also known as http.js, to send HTTP requests from YouTrack to external services. This sandboxed HTTP client runs inside the YouTrack backend and is the basis for integrations that need to call other tools.
For further information, see http.
Backend Data Storage
YouTrack stores backend app data in its database. Use the storage option that matches the scope of the value.
Storage option | Scope | Typical data |
|---|---|---|
A core YouTrack entity, such as an issue, article, project, or user. | App-owned data that belongs to a specific entity. | |
The app itself, without linking the value to a specific YouTrack entity. | App-owned data that is shared across backend modules. | |
Global or project-level app configuration. | Administrator-configured values and secret credentials for backend integrations. |