Deployment

Deploying Builder use cases requires a structured approach to move your solutions from development to production. This guide outlines strategies for versioning, deploying, and managing applications across different environments to ensure reliability and performance.

Deployment Strategies

Single Workspace
Multi-Workspace
Multi-Instance

Best for: Basic applications with minimal complexity, such as simple prompting agentsIn this approach, you use a single workspace for both development and production:

Development: Create and test your application directly in the workspace
Production: Once tested, the same workspace serves as the production environment
Version Control: Use versioning to save stable points for potential rollback

Advantages:

Simplest deployment approach
No need to migrate between workspaces
Quick iteration and updates

Considerations:

Limited separation between development and production
Higher risk of disruptive changes affecting live users
Best suited for applications with low complexity and minimal regulatory constraints

Clicking Deploy in the Builder header bar opens a modal with two tabs: Publish and Share.

Publish tab

The Publish tab turns the current workspace source into a runnable bundle and assigns it a version.

Field / control	What it does
Version name	A free-form identifier for this deploy (defaults to an auto-incremented semver after the latest deployed version). Shown in the read-only version dropdown of the header bar once deployed.
Publish button	Synchronizes any unsaved source files to the workspace, builds the React/Vite bundle, and registers it as the workspace’s current deployed bundle. On success the modal shows the bundle URL and the ready-to-embed snippet.

Every Publish action persists three things:

The bundled JavaScript (served at /builtin-bundles/<slug>.<hash>.js).
The new entry in the workspace versions history.
A workspaces.versions.published event in the workspace Activity feed.

A deployed bundle can be viewed read-only under the Pages sidebar entry until a newer version is published or rolled back. The Share tab generates the public links and embed snippets needed to expose the deployed bundle outside the Builder.

Platform URL

A copyable URL of the form https://<platform-host>/apps/<workspace-slug>. This is the workspace runtime URL: anyone with workspace access can open the deployed app at that address.

Embed modes

Four mutually exclusive display modes are exposed. Each one generates a <script> tag that you paste into any host page; the script is /embed.js shipped by the platform, which boots a React 18 runtime and mounts the deployed bundle.

Mode	What it renders on the host page	When to use it
Inline	A normal block inside a container you control (defaults to `#prisme-app`).	The app is a regular section of the host page.
Popover	A floating bubble pinned to the bottom-right of the viewport that expands into a chat-style panel on click.	Customer-support agents, in-page assistants.
Modal	A fullscreen overlay opened by a trigger element you control (defaults to `#open-app`).	Heavy interactive flows that should not share the host page real estate.
Bottom Sheet	A panel that slides up from the bottom of the viewport on a trigger click.	Mobile-first integrations.

Generated snippet

The Share tab writes the snippet directly into the modal; copy it as-is. Examples for each mode:

<!-- Inline: embed inside a container you place on the host page -->
<div id="prisme-app"></div>
<script src="https://<platform-host>/embed.js"
  data-bundle-url="/builtin-bundles/<slug>.<hash>.js"
  data-workspace-id="<workspace-id>"
  data-mode="inline"
  data-container="#prisme-app"
></script>

<!-- Popover: floating bubble bottom-right, no markup needed on the host page -->
<script src="https://<platform-host>/embed.js"
  data-bundle-url="/builtin-bundles/<slug>.<hash>.js"
  data-workspace-id="<workspace-id>"
  data-mode="popover"
></script>

<!-- Modal / Bottom Sheet: provide a trigger button on the host page -->
<button id="open-app">Open the assistant</button>
<script src="https://<platform-host>/embed.js"
  data-bundle-url="/builtin-bundles/<slug>.<hash>.js"
  data-workspace-id="<workspace-id>"
  data-mode="modal"
  data-trigger="#open-app"
></script>

`data-*` attributes

Attribute	Required	Description
`data-bundle-url`	recommended	URL of the deployed bundle. If omitted, `embed.js` fetches `/builtin-bundles/bundle-map.json` and looks up the bundle by app slug.
`data-workspace-id`	yes	The workspace whose runtime context (auth, events, SDK) the app will receive.
`data-mode`	yes	`inline`, `popover`, `modal`, or `bottom-sheet`. Case-sensitive.
`data-container`	inline only	CSS selector of the host element. Defaults to `#prisme-app`.
`data-trigger`	modal / bottom-sheet	CSS selector of the element that opens the overlay. Defaults to `#open-app`.
`data-theme`	no	`light` or `dark`. Forwarded to the app via `props.theme`.
`data-primary-color`, `data-background-color`	no	Override the app’s CSS variables for branding.
`data-auth`	no	Pre-supplied authentication strategy (e.g. a JWT) when the host page already knows the user.

Bundle hosting and CORS

The bundle is fetched cross-origin with mode: 'cors', so the server returning /builtin-bundles/<slug>.<hash>.js must reply with Access-Control-Allow-Origin: * (the platform sets this header by default). If you self-host the bundle behind a CDN or proxy, preserve the header. embed.js injects its own CSS and loads Tailwind from cdn.tailwindcss.com. The host page’s CSP must allow:

script-src for the platform host and esm.sh,
style-src 'unsafe-inline' and cdn.tailwindcss.com,
connect-src for the platform API host.

Update flow

Publish → Share is a single cycle. To roll an embed forward, redeploy from the Publish tab — the bundle URL changes (its hash is content-addressed), so re-copy the snippet into the host page. Hosts that omit data-bundle-url will pick up the new version automatically because bundle-map.json is updated by every Publish.

Versioning Your Application

Workspaces can be synchronized with Git repositories to version your application, enabling push/pull workflows, collaboration, and rollback capabilities. For complete documentation on repository configuration, authentication methods, push/pull operations, merge conflict handling, and bulk operations, see the dedicated Versioning page.

API deployment

Here is a small example script using archive export/import APIs to update a workspace from another :

// Example Node.js deployment script
async function deployWorkspace(sourceId, targetId, accessToken) {
  // Export source workspace
  const exportResponse = await fetch(`https://api.studio.prisme.ai/v2/workspaces/${sourceId}/export`, {
    headers: { 'Authorization': `Bearer ${accessToken}` },
  });
  const archive = await exportResponse.blob();

  // Import to target workspace
  const form = new FormData();
  form.append('archive', archive, 'workspace.zip');

  await fetch(`https://api.studio.prisme.ai/v2/workspaces/${targetId}/import`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}` },
    body: form,
  });

  console.log('Deployment completed successfully');
}

deployWorkspace('source-workspace-id', 'target-workspace-id', 'your-access-token');

CI/CD deployment

CI-based deployment enables more complex scenarios, especially useful for multi-instance environments where you need to promote workspaces from a development/sandbox instance to production instances. The general approach is:

Push workspaces to a Git repository from the source environment (bulk push via API)
Build a Docker image embedding those workspaces into the prismeai-workspaces service
Deploy the image to the target environment, where workspaces are automatically imported at startup

An alternative scenario without building docker image could be to bulk import the source git repository directly into the destination environment.
However, the scenario described here have the following advantages :

CI/CD enable additional security and quality guardrails during the upgrade process
The dest environment do not need any network access to the source environement git, and can be upgraded / roll-backed at any time even if the git is not available

Prerequisites

Platform repository on the source environment

Configure a platform repository on your source environment (e.g. sandbox) so that all workspaces can be pushed to a shared Git repository:

# Platform repository pointing to your Git server
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_NAME=My Workspaces
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_URL=https://gitlab.com/myorg/workspaces.git
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_BRANCH=sandbox
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_DIRPATH=workspaces
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_AUTH_USER=my-user
WORKSPACES_STORAGE_GIT_PLATFORM_myrepo_AUTH_PASSWORD=my-token

Workspace groups

Define workspace groups to organize which workspaces should be included in your releases:

WORKSPACES_GROUP_base1_LABELS="production:app:base1"
WORKSPACES_GROUP_base2_LABELS="production:app:base2"
WORKSPACES_GROUP_extended_LABELS="production:app,production:product"

Workspaces are assigned to groups through their labels. During a bulk push, only workspaces matching the requested groups are included.

Step 1: Bulk push workspaces to Git

Use the bulk push API to export all workspace groups to the platform repository. This is typically the first stage of your CI/CD pipeline:

# GitLab CI example
version_workspaces:
  stage: version
  script:
    - |
      curl -N -w "\n__HTTP_STATUS__:%{http_code}" \
        "${SOURCE_API_URL}/v2/workspaces/platform/versions?sse=true" \
        --header 'Content-Type: application/json' \
        --header "Authorization: Bearer ${SOURCE_ACCESS_TOKEN}" \
        --data '{
          "repository": {"id": "myrepo"},
          "groups": ["base1", "base2", "extended"]
        }' | tee /tmp/sse_output.txt

      # Check HTTP status
      HTTP_CODE=$(grep -o '__HTTP_STATUS__:[0-9]*' /tmp/sse_output.txt | tail -1 | cut -d: -f2 || true)
      if [ -n "$HTTP_CODE" ] && { [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; }; then
        echo "ERROR: API returned HTTP $HTTP_CODE"
        exit 1
      fi

      # Check for errors in the final SSE event
      LAST_DATA=$(grep "^data: " /tmp/sse_output.txt | tail -1 | sed 's/^data: //' || true)
      if [ -z "$LAST_DATA" ]; then
        echo "ERROR: No SSE data received in response"
        exit 1
      fi
      ERRORS=$(echo "$LAST_DATA" | jq '.errors | length')
      CONFLICTS=$(echo "$LAST_DATA" | jq '.mergeConflictWorkspaceIds | length')
      if [ "$ERRORS" -gt 0 ] || [ "$CONFLICTS" -gt 0 ]; then
        echo "ERROR: Bulk push to git failed with errors or merge conflicts:"
        echo "$LAST_DATA" | jq '.'
        exit 1
      fi
      echo "All workspaces successfully versioned."

The ?sse=true parameter enables Server-Sent Events for real-time progress tracking, which is recommended for CI pipelines to avoid HTTP timeouts on large deployments.

Step 2: Build a Docker image with embedded workspaces

Once workspaces are pushed to Git, build a custom prismeai-workspaces Docker image that embeds them. This uses a Dockerfile that:

Clones the workspaces repository
Runs a security scan (e.g. TruffleHog) to detect leaked secrets
Copies the workspace files into the image
Configures a filesystem-type platform repository pointing to the embedded files

ARG BASE_IMAGE

# Security scan stage
FROM alpine:3.20 AS security-scan
ARG WORKSPACES_REPO_URL
ARG WORKSPACES_REPO_BRANCH=main
ARG WORKSPACES_REPO_SUBDIR=""

RUN apk add --no-cache git curl && \
    curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \
    | sh -s -- -b /usr/local/bin

RUN git clone --depth 1 -b "$WORKSPACES_REPO_BRANCH" "$WORKSPACES_REPO_URL" /tmp/repo

RUN SCAN_DIR=$(if [ -n "$WORKSPACES_REPO_SUBDIR" ]; then \
      echo "/tmp/repo/$WORKSPACES_REPO_SUBDIR"; else echo "/tmp/repo"; fi) && \
    EXCLUDE_FILE=$(mktemp) && \
    echo '.*import\.yml' > "$EXCLUDE_FILE" && \
    trufflehog filesystem "$SCAN_DIR" -x "$EXCLUDE_FILE" --json --fail

# Build stage
FROM $BASE_IMAGE
ARG WORKSPACES_REPO_SUBDIR=""
ARG WORKSPACES_VERSION_NAME=""

# Make sure we get rid of previous workspaces if we're rebuilding this multiple times from / to the  same tag
RUN rm -rf /tmp/repo && rm -rf /www/workspaces
COPY --from=security-scan /tmp/repo /tmp/repo
RUN if [ -n "$WORKSPACES_REPO_SUBDIR" ]; then \
      mv "/tmp/repo/$WORKSPACES_REPO_SUBDIR" /www/workspaces; \
    else \
      mv /tmp/repo /www/workspaces; \
    fi && \
    rm -rf /www/workspaces/.git /tmp/repo

# Same workspace groups as defined in source environment 
ENV WORKSPACES_GROUP_base1_LABELS "production:app:base1"
ENV WORKSPACES_GROUP_base2_LABELS "production:app:base2"
ENV WORKSPACES_GROUP_extended_LABELS "production:app,production:product"

# Filesystem platform repository pointing to embedded workspaces
ENV WORKSPACES_STORAGE_GIT_PLATFORM_release_NAME "Release ${WORKSPACES_VERSION_NAME}"
ENV WORKSPACES_STORAGE_GIT_PLATFORM_release_TYPE "filesystem"
ENV WORKSPACES_STORAGE_GIT_PLATFORM_release_DIRPATH "/www/workspaces"
ENV WORKSPACES_STORAGE_GIT_PLATFORM_release_MODE "read-only"

The key part is the filesystem platform repository at the end: it tells the workspaces service to treat the embedded /www/workspaces directory as a read-only platform repository named “release”. This allows the target environment to use the standard bulk import mechanism to import workspaces from the Docker image itself, without needing Git credentials. The CI job to build this image:

build_workspaces_image:
  stage: build
  needs: [version_workspaces]
  image: docker:25
  services:
    - docker:25-dind
  variables:
    WORKSPACES_REPO_BRANCH: "sandbox"
    WORKSPACES_REPO_SUBDIR: "workspaces"
  script:
    - >
      docker build
      --build-arg BASE_IMAGE=${WORKSPACES_IMAGE}:${BASE_TAG}
      --build-arg WORKSPACES_REPO_URL=https://ci-token:${CI_TOKEN}@gitlab.com/myorg/workspaces.git
      --build-arg WORKSPACES_REPO_BRANCH=${WORKSPACES_REPO_BRANCH}
      --build-arg WORKSPACES_REPO_SUBDIR=${WORKSPACES_REPO_SUBDIR}
      --build-arg WORKSPACES_VERSION_NAME=${CI_COMMIT_TAG:-latest}
      -t ${WORKSPACES_IMAGE}:${IMAGE_TAG}
      -f with-workspaces.Dockerfile .
    - docker push ${WORKSPACES_IMAGE}:${IMAGE_TAG}

Step 3: Deploy and import on the target environment

Deploy the custom image to your target environment (e.g. production). On startup, workspaces can be automatically imported using the STARTUP_IMPORT_* environment variables:

# Automatically import workspaces from the embedded filesystem repository at startup
STARTUP_IMPORT_REPOSITORY=release
STARTUP_IMPORT_GROUPS=base1,base2,extended

This triggers a bulk import each time the workspaces service starts, importing all workspaces from the groups that match. Workspaces already up to date (based on version name comparison) are skipped automatically. Alternatively, you can trigger the import manually via the API after deployment:

curl -X POST "${PROD_API_URL}/v2/workspaces/platform/versions/latest/pull" \
  -H "Authorization: Bearer ${PROD_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"repository": {"id": "release"}, "groups": ["base1", "base2", "extended"]}'

Or you can also start these imports manually from the Platform workspace UI.

Summary

The complete CI/CD flow looks like this:

Source environment                    Git repository                Target environment
┌──────────────┐     bulk push      ┌──────────────┐              ┌──────────────┐
│   Sandbox    │ ──────────────────► │  workspaces  │              │  Production  │
│  workspaces  │                     │    repo      │              │              │
└──────────────┘                     └──────┬───────┘              └──────▲───────┘
                                            │                            │
                                     docker build                  bulk import
                                            │                     (at startup)
                                     ┌──────▼───────┐                    │
                                     │ Docker image  │                   │
                                     │  (embedded    │ ──── deploy ──────┘
                                     │  workspaces)  │
                                     └──────────────┘

Environment-Specific Configuration

Manage differences between environments:

Use Workspace Secrets

Store environment-specific values as secrets:

# In development workspace
secrets:
  apiEndpoint: https://dev-api.example.com
  maxRequests: 10

# In production workspace
secrets:
  apiEndpoint: https://api.example.com
  maxRequests: 100

Access these values in your application using:

{{secret.apiEndpoint}}

Conditional Logic

Implement environment-aware behavior in automations:

# Example automation with environment detection
slug: processData
do:
  - conditions: 
    "{{environment}} == 'production'":
      - callAPI:
          url: "{{secret.productionApi}}"
    default:
      - callAPI:
          url: "{{secret.developmentApi}}"

This allows your applications to adapt to different environments.

Deployment Best Practices

Version Everything

Maintain complete history of your application:

Commit changes frequently with clear messages
Use branches for feature development
Tag important releases (e.g., v1.0.0)
Document significant version changes
Never work directly in production

Test Before Deployment

Validate thoroughly before moving to production:

Test in development environment first
Verify integrations with external systems
Test with realistic data sets
Include user acceptance testing
Conduct security testing

Controlled Deployment

Implement safeguards around deployment:

Use approval workflows for production changes
Deploy during low-traffic periods
Implement monitoring during deployment
Prepare rollback procedures
Document deployment steps

Environment Isolation

Maintain clear boundaries between environments:

Use separate API keys for each environment
Configure different external service endpoints
Apply appropriate security controls by environment
Use visual indicators to distinguish environments
Limit production access to necessary personnel

Troubleshooting Deployments

Infrastructure issues

First check that your infrastructure is properly configured and running with readiness API.

Import/Pull Failures

Common causes and solutions for import problems:Issue: Slug Conflicts

"Could not rename workspace slug from {oldSlug} to {newSlug} as it is already used"

Solution: Ensure unique slugs across workspaces or exclude index file from import.

For Platform bulk imports, check the detailed errors list in workspaces.bulkImport.completed event.
For bulk archive imports, check the same detailed errors list in prismeai-workspaces container logs.
Individual workspace import errors an also be checked in the workspaces.imported event emitted in their activity feed.

Rollback Procedures

How to revert to a previous state:Platform rollback:

Identify the stable version tag
Revert prismeai images to that tag
Open Platform workspace and pull again all 3 native goups one after another : base1, base2, extended.

Workspace git versioning :

Open the workspace activity feed
Filter events on type workspaces.versions.published
Use the native “Rollback” UI button to roll back to the desired version

Export/Import Rollback:

Maintain archives of known-good workspace states
Import the last stable archive if issues occur

Best Practice: Test rollback procedures regularly to ensure they work when needed.

Next Steps

RBAC

Configure role-based access control across environments

Integrations

Connect your applications to external systems

Testing & Debugging

Learn how to thoroughly test applications before deployment

Overview

Chat

Agent Creator

Knowledges

Builder

Governe

Insights

Deployment Strategies

Publish tab

Platform URL

Embed modes

Generated snippet

`data-*` attributes

Bundle hosting and CORS

Update flow

Versioning Your Application

API deployment

CI/CD deployment

Prerequisites

Platform repository on the source environment

Workspace groups

Step 1: Bulk push workspaces to Git

Step 2: Build a Docker image with embedded workspaces

Step 3: Deploy and import on the target environment

Summary

Environment-Specific Configuration

Deployment Best Practices

Version Everything

Test Before Deployment

Controlled Deployment

Environment Isolation

Troubleshooting Deployments

Next Steps

RBAC

Integrations

Testing & Debugging

Overview

Chat

Agent Creator

Knowledges

Builder

Governe

Insights

Documentation Index

​Deployment Strategies

​The Deploy Modal

​Publish tab

​Share tab

​Platform URL

​Embed modes

​Generated snippet

​data-* attributes

​Bundle hosting and CORS

​Update flow

​Versioning Your Application

​API deployment

​CI/CD deployment

​Prerequisites

​Platform repository on the source environment

​Workspace groups

​Step 1: Bulk push workspaces to Git

​Step 2: Build a Docker image with embedded workspaces

​Step 3: Deploy and import on the target environment

​Summary

​Environment-Specific Configuration

​Deployment Best Practices

Version Everything

Test Before Deployment

Controlled Deployment

Environment Isolation

​Troubleshooting Deployments

​Next Steps

RBAC

Integrations

Testing & Debugging

Deployment Strategies

The Deploy Modal

Publish tab

Share tab

Platform URL

Embed modes

Generated snippet

`data-*` attributes

Bundle hosting and CORS

Update flow

Versioning Your Application

API deployment

CI/CD deployment

Prerequisites

Platform repository on the source environment

Workspace groups

Step 1: Bulk push workspaces to Git

Step 2: Build a Docker image with embedded workspaces

Step 3: Deploy and import on the target environment

Summary

Environment-Specific Configuration

Deployment Best Practices

Troubleshooting Deployments

Next Steps