Vertesia Documentation

What are Applications?

Applications are the way to customize the Vertesia platform for your projects. By creating an application you can:

  1. Contribute UI applications focused on the business model of your organization / project.
  2. Contribute custom tools.
  3. Contribute content types to your project.

Applications are installed at project level.

Creating an application

Applications are created by registering the application manifest in Vertesia Studio > Settings > Available Apps page.

Each application must have an unique name in kebab case. We recommend prefixing the name of your application using your organization name: vertesia-review-center, foo-contracts etc.

Application manifest

An application manifest is implementing the following interface:

interface AppManifestData {
    /**
     * The name of the app, used as the id in the system.
     * Must be in kebab case (e.g. my-app).
     */
    name: string;

    /**
     * Visibility of the app: "public", "private", or "vertesia".
     * Private apps are only visible to the owner organization.
     */
    visibility: "public" | "private" | "vertesia";

    title: string;
    description: string;
    publisher: string;

    /**
     * A svg icon for the app.
     */
    icon?: string;

    status: "beta" | "stable" | "deprecated";

    ui?: {
        /**
         * The source URL of the app. For iframe isolation this is the standalone
         * application URL. For legacy plugin modes it is an ESM bundle URL.
         * The src can be a template which contain
         * a variable named `buildId` which will be replaced with the current build id.
         * For example: `/plugins/vertesia-review-center-${buildId}`
         */
        src: string;
        
        /**
         * The isolation strategy. New customer apps should use iframe.
         * - iframe - run a standalone app with its own dependencies and document.
         * - shadow - use Shadow DOM to fully isolate the plugin from the host.
         * - css - use CSS processing (like prefixing or other isolation techniques). Lighter but plugins may conflict with the host
         */
        isolation?: "iframe" | "shadow" | "css";
    },

    /**
     * MCP server configurations for external tool integrations.
     * See the Tool Collections page for full configuration options.
     */
    tool_collections?: ToolCollection[];

    /**
     * The app endpoint URL. Tools, interactions, UI, and settings
     * are discovered automatically from this URL.
     */
    endpoint?: string;
}

Applications can be private or public. Private applications can only be installed in projects of the same organization as the one who defined the application. The application will not be visible in other organizations. Public applications are visible in all organizations.

In order to use an application you need to install it on a project.

Installing an application on a project

Open the Installations tab in the applications settings page to see the list of the installed applications in the current project or to install a new application.

After installing the application you must define the users or groups that can access the application. This can be done using the Manage permissions button.

Contributing UI applications

Customer applications are loaded as standalone documents in sandboxed iframes. Set ui.src to the application URL and ui.isolation to iframe. The app owns React and its complete dependency graph, so a Studio CDN dependency upgrade cannot change the app at runtime. Studio bootstraps the existing user session through an origin-checked in-memory handshake and reacquires it when the embedded session needs refreshing; direct visits use the normal sign-in flow. The iframe bridge also synchronizes route, account/project, locale, and theme state with Composite Apps. Generated apps advertise both app_portal and composite_app availability by default.

Iframe isolation is a DOM and dependency boundary, not a credential boundary. The trusted application origin receives the viewing user's Studio JWT in memory, so ui.src must point to an origin trusted with that user's Vertesia access. It must also differ from the Studio origin; that separation is required for the iframe sandbox to remain an effective DOM boundary.

The shadow and css modes remain available for legacy and first-party platform extensions that are deliberately compiled as host-React plugin modules.

Installed Applications that contribute an UI application are visible on the Vertesia Studio UI landing page for users who have the permission to access the application.

To learn how to develop an application UI, go to the Application UI section.

Contributing custom tools

Custom tools are contributed via the endpoint property — Vertesia automatically discovers tools from the endpoint URL. These servers can expose both regular tools and skills. Skills appear to agents as tools whose names start with the learn_ prefix and cooperate with the Daytona sandbox and execute_shell for advanced code and data workflows. To learn how to write a tools server, see Custom Tools.

Note that only the users that can access the application can use these tools.

Example:

{
  "name": "my-app",
  "endpoint": "https://my-tools-server.com/api/vertesia"
}

Contributing MCP Servers

To connect external MCP servers, use the tool_collections property. MCP servers support OAuth authentication. See MCP Servers for full configuration options.

Example:

{
  "name": "my-app",
  "tool_collections": [
    {
      "type": "mcp",
      "url": "https://mcp.my-crm-provider.com",
      "name": "My CRM",
      "description": "CRM tools for contacts and deals",
      "namespace": "crm",
      "auth": "oauth",
      "oauth_app": "my-crm-oauth"
    }
  ]
}

Contributing content types

Work is in progress for this feature.

Was this page helpful?