Deployment

Deploying AI 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

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

AI SecureChat

AI Store

AI Knowledge

AI Builder

AI Governance

AI Collection (beta)

AI Insights (beta)

Deployment Strategies

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

AI SecureChat

AI Store

AI Knowledge

AI Builder

AI Governance

AI Collection (beta)

AI Insights (beta)

​Deployment Strategies

​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

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