Complete Setup and Usage Guide: On-Prem AI + SCIM with Microsoft Entra

This guide is designed to help you get started with Swimm, and to provide you with a quick reference for the most common tasks you'll perform while using Swimm.

This comprehensive guide covers everything from technical workspace setup to day-to-day usage of Swimm. It's designed for both administrators configuring the workspace and team members using Swimm.

Part 1: Workspace Setup (For Administrators)​

This section covers the technical setup required by workspace administrators before team members can start using Swimm.

1.1 On-Prem AI Setup​

Swimm's On-Prem Agent is a dedicated server running in a container within your company's network. It grants Swimm access to services you host internally (like Azure OpenAI) without sharing credentials directly with Swimm, keeping your keys confidential and private.

Prerequisites​

Before deploying the On-Prem Agent, ensure you have:

1. Azure OpenAI models for GPT-4.1, GPT-4.1 mini, and GPT-3.5 Turbo Instruct if deploying for AI features:

   • API Key
   • Deployment URL
     
     

   See:

   • Deploying Models
   • How to get the deployment URL
     
     

2. The server is required to be deployed with HTTPS/TLS configured with a certificate trusted by your organization's computers. See TLS Configuration.

3. The deployed container will be exposed to the Swimm IDE extension and web page in order to bridge Azure OpenAI with Swimm. Make sure that your network allows inbound traffic to this container from the developers' machines.

4. The server requires access to the domain https://app.swimm.io to function correctly, please make sure that is allowed.

5. If you direct the agent to connect to Azure OpenAI via a forward/reverse proxy/VPN, and that proxy/VPN does TLS Man-in-the-Middle (MITM), you will need to configure the On-Prem Agent to trust the certificate of the proxy/VPN. You can configure an additional certificate bundle that the On-Prem Agent will use by using the NODE_EXTRA_CA_CERTS environment variable. See the FAQ for more details.

6. Swimm uses Azure OpenAI streaming API, the On-Prem Agent will stream the responses from the Azure OpenAPI instance using SSE (Server-Sent Events) the same as a direct streaming request to Azure OpenAI. Make sure that your network, load balancer/proxy, and container orchestration platform allows SSE. You can verify this by checking documentation of your load balancer/proxy/container orchestration platform, or by asking the relevant personnel at your organization that is responsible for it.

Technical Details​

• The server listens on port 24605 inside the container by default, this can be overriden using the PORT environment variable. Though you can also always remap the outside port using Docker port mapping.
• The server has an HTTP health check endpoint at /health.
• The path to the configuration file inside the container defaults to /etc/swimm/onprem-agent.yaml, but can be overriden using the CONFIG_PATH environment variable.

Deploying Models​

To use Swimm's On-Prem Agent with your own Azure OpenAI instance, you need to deploy the required models in your Azure OpenAI resource.

Microsoft documentation: How to deploy Azure OpenAI models with Azure AI Foundry

1. Enter Azure AI Foundry, creating or selecting the correct Azure OpenAI resources at the top.

   Or enter Azure Portal → Azure OpenAI → Create/Select OpenAI Resource → Explore Azure AI Foundry Portal

2. Select Deployments in the sidebar.

3. Select Deploy model.

4. Deploy gpt-4.1, gpt-4.1-mini and gpt-35-turbo-instruct with a name of your choice.

How to Get the Deployment URL​

Click your deployed model in the Azure AI Foundry portal to see its target URI. The URL you need is without the /chat/completions and ?api-version=* suffixes. For example:

Installation Steps​

Step 1: Pull the Docker Image​

If needed, pull the latest version of the image using:

docker pull swimmio/onprem-agent:3 # From Docker Hub
# Or
docker pull us-docker.pkg.dev/swimmio/public/onprem-agent:3 # From Google Artifact Registry

The image is on Docker Hub swimmio/onprem-agent and Google Artifact Registry. You can see the available tags there if you want to pin the version to have more control over updates. We publish the following tags:

• latest - Always the latest version.
• 3, 2, 1 - The latest release for each major version (e.g., 3 is the latest major version 3).
• 3.0.0 - A specific version.

In case you don't want to, or have no access, to use Docker Hub or Google Artifact Registry, you can also mirror the image:

docker save swimmio/onprem-agent:3 --platform linux/amd64 -o swimm-onprem-agent-3.tar # From Docker Hub
# Or
docker save us-docker.pkg.dev/swimmio/public/onprem-agent:3 --platform linux/amd64 -o swimm-onprem-agent-3.tar # From Google Artifact Registry

docker load -i swimm-onprem-agent-3.tar

docker tag <image> <your-registry>/<image> # e.g. docker tag swimmio/onprem-agent:latest registry.foo.test/swimmio/onprem-agent:latest
docker push <your-registry>/<image> # e.g. docker push registry.foo.test/swimmio/onprem-agent:latest

Step 2: Configure the Agent​

Configuring On-prem Enterprise Git Provider (if needed)​

For more information on how to create a Swimm OAuth App for your on-prem Git hosting, please refer to the following instructions:

• GitHub Enterprise Server
• GitLab Server

Creating the Configuration File​

Create your configuration file using the template below:

Configuration sections:

git

• GitHub Enterprise Server and GitLab Server only.
• If you're using on-premises Bitbucket Data Center or cloud-hosted git providers (GitHub.com, GitLab.com, Bitbucket Cloud and Azure DevOps), you should remove the entire git section.

ai

• Configure your Azure OpenAI deployments and API credentials for AI features.
• If you're not using on-premises AI features, you should remove the entire ai section.

# yaml-language-server: $schema=https://docs.swimm.io/schemas/onprem-agent-config.json

# For single-tenant customers only, configure the URL of your Swimm instance (e.g. https://foo-bar-swimm.com)
# swimmBaseUrl: <swimm_instance_url>

# For configuring On-Prem/Enterprise Git Provider authentication (GitHub Enterprise Server / GitLab Server only), remove if Bitbucket Data Center or cloud git providers are used
git:
  provider: <github | gitlab>
  host: <git_server_url>
  oauth:
    clientId: <client_id>
    clientSecret: <client_secret>

# For configuring AI features, remove if not used
ai:
  models:
    short:
      provider: azureOpenAI
      deployment: <gpt-4.1-mini-deployment-name>
      model: gpt-4.1-mini
    long:
      provider: azureOpenAI
      deployment: <gpt-4.1-deployment-name>
      model: gpt-4.1
    completion:
      provider: azureOpenAI
      deployment: <gpt-35-turbo-instruct-deployment-name>
      model: gpt-3.5-turbo-instruct

  providers:
    azureOpenAI:
      endpoint: https://<azure-openai-resource>.openai.azure.com
      apiKey: <azure_openai_api_key>

Step 3: Deploy the Agent​

The On-Prem Agent is a Docker container that can be deployed on any platform. Choose your deployment method:

docker run -d \
  -p 24605:24605 \
  -v $PWD/swimm-onprem-agent.yaml:/etc/swimm/onprem-agent.yaml:ro \
  -e CONFIG_PATH=/etc/swimm/onprem-agent.yaml \
  swimmio/onprem-agent:3

services:
  onprem-agent:
    image: swimmio/onprem-agent:3
    ports:
      - 24605:24605
    volumes:
      - ./swimm-onprem-agent.yaml:/etc/swimm/onprem-agent.yaml:ro
    environment:
      CONFIG_PATH: /etc/swimm/onprem-agent.yaml

docker compose up -d

apiVersion: v1
kind: Secret
metadata:
  name: onprem-agent-config
# Replace <onprem-agent-config> with the contents of your configuration file
# properly indented, or use kubectl create secret or kustomize using
# secretGenerator to load this from a file, or any such similar tool
stringData:
  onprem-agent.yaml: |
    <onprem-agent-config>

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onprem-agent
  labels:
    app: onprem-agent
spec:
  selector:
    matchLabels:
      app: onprem-agent
  template:
    metadata:
      labels:
        app: onprem-agent
    spec:
      containers:
      - name: onprem-agent
        image: swimmio/onprem-agent:3 # Should probably pin to a specific version, e.g. swimmio/onprem-agent:3.0.0 due to how Kubernetes works
        ports:
        - containerPort: 24605
        volumeMounts:
        - name: config
          mountPath: /etc/swimm
          readOnly: true
        env:
        - name: CONFIG_PATH
          value: /etc/swimm/onprem-agent.yaml
        resources:
          requests:
            memory: 512Mi
            cpu: '1'
          limits:
            memory: 512Mi
            cpu: '1'
        readinessProbe:
          initialDelaySeconds: 5
          periodSeconds: 3
          httpGet:
            port: 24605
            path: /health
            # Uncomment if you configured TLS in the On-Prem Agent configuration
            # scheme: HTTPS
        # TODO Do we want a livenessProbe?
      volumes:
      - name: config
        secret:
          secretName: onprem-agent-config
      securityContext:
        runAsNonRoot: true

apiVersion: v1
kind: Service
metadata:
  name: onprem-agent-ingress-svc
spec:
  type: NodePort
  selector:
    app: onprem-agent
  ports:
  - port: 24605
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: onprem-agent
spec:
  # ingressClassName: nginx
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: onprem-agent-ingress-svc
            port:
              number: 24605

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: onprem-agent
spec:
  gatewayClassName: nginx
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: onprem-agent.example.internal
    tls:
      mode: Terminate # If protocol is `TLS`, `Passthrough` is a possible mode
      certificateRefs:
      - group: ""
        kind: Secret
        name: <onprem-agent-cert>

apiVersion: v1
kind: Service
metadata:
  name: onprem-agent-gateway-svc
spec:
  type: NodePort
  selector:
    app: onprem-agent
  ports:
  - port: 24605
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: onprem-agent-httproute
spec:
  parentRefs:
  - name: <onprem-agent-gateway>
  rules:
  - backendRefs:
    - name: onprem-agent-gateway-svc
      port: 24605

apiVersion: v1
kind: Service
metadata:
  name: onprem-agent
spec:
  # You will need to configure HTTPS in the load balancer, or use a separate proxy that and NodePort
  type: LoadBalancer
  selector:
    app: onprem-agent
  ports:
  - port: 8080 # Or 443 if you configured HTTPS in the onprem-agent config
    targetPort: 24605

aws sts get-caller-identity --query Account --output text

# This used the default project, feel free to replace with a different one
PROJECT_ID=$(gcloud config get project)
# Feel free to pick a different region
REGION=us-central1

# A dedicated service account for the On-Prem Agent
gcloud iam service-accounts create swimm-onprem-agent \
  --display-name "Swimm's On-Prem Agent" \
  --description "Swimm's On-Prem Agent Service Account"

# The config secret
gcloud secrets create swimm-onprem-agent-config \
  --data-file=swimm-onprem-agent.yaml

# Add permissions to the service account to access the secret
gcloud secrets add-iam-policy-binding swimm-onprem-agent-config \
  --member=serviceAccount:swimm-onprem-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor

# Deploy the On-Prem Agent
gcloud run deploy swimm-onprem-agent \
  --image=us-docker.pkg.dev/swimmio/public/onprem-agent:3 \
  --no-invoker-iam-check \
  --region=$REGION \
  --service-account=swimm-onprem-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --startup-probe=initialDelaySeconds=5,periodSeconds=3,timeoutSeconds=1,httpGet.port=8080,httpGet.path=/health \
  --set-env-vars=CONFIG_PATH=/etc/swimm/onprem-agent.yaml \
  --set-secrets=/etc/swimm/onprem-agent.yaml=swimm-onprem-agent-config:latest

gcloud run services describe --region=$REGION swimm-onprem-agent --format="get(status.url)"

Step 4: Verify the Installation​

In your browser on the client machines that are going to connect to the onprem-agent, browse to:

https://<your-service-url>/status

This should let you know if the service is up and running, and if the configuration is working correctly to communicate with your Azure OpenAI deployment.

You can also try from a terminal:

curl -v https://<your-service-url>/health

Step 5: Provide Service URLs to Swimm​

Setting Up a Budget Alert​

The Azure Open AI token is not technically limited to a certain amount of API calls or budget, so it's better to have an alert for unusual/unauthorized usage.

Here is a short video that shows how to do that:

1.2 SCIM with Microsoft Entra Setup​

SCIM (System for Cross-domain Identity Management) provisioning with Microsoft Entra ID enables automatic user and group synchronization to your Swimm workspace.

Prerequisites​

Before setting up SCIM, ensure you have:

• Admin access to your Microsoft Entra ID tenant
• Admin access to your Swimm workspace
• The SCIM tenant URL and secret token provided by Swimm

Setup Steps​

Step 1: Navigate to Microsoft Entra ID​

In the Azure portal, go to Microsoft Entra ID from the main navigation menu.

Step 2: Access Enterprise Applications​

From the Microsoft Entra ID overview page, navigate to Enterprise applications under the Manage section.

Step 3: Create a New Enterprise Application​

Click New application to create a new enterprise application for Swimm SCIM integration.

Step 4: Configure Provisioning Settings​

Navigate to the Provisioning section of your newly created application and enter:

• Tenant URL: https://mycompany-swimm.io/api/scim
• Secret Token: The token provided by your Swimm workspace administrator

Click Test Connection to verify the configuration.

Step 5: Enable Provisioning​

Once the test connection is successful:

1. Set Provisioning Mode to Automatic
2. Configure your Mappings and Settings as needed
3. Set Provisioning Status to On
4. Click Save to apply changes

Next Steps​

After enabling provisioning:

• Users and groups assigned to this enterprise application will be automatically provisioned to your Swimm workspace
• User lifecycle changes (additions, updates, deactivations) will be automatically synchronized
• Monitor provisioning activity in the Provisioning logs section

Troubleshooting SCIM​

If you encounter issues:

• Verify the tenant URL and secret token are correct
• Check that the enterprise application is assigned to appropriate users and groups
• Review provisioning logs for detailed error messages
• Ensure your Swimm workspace has SCIM provisioning enabled

Part 2: Getting Started (For All Users)​

Once your administrator has completed the workspace setup, you can start using Swimm.

2.1 Create Your Swimm Account​

To get started with Swimm, create a user account under your organization's workspace. Once you've created an account and logged in, you'll notice that your admin may have added repositories to the workspace for your organization's git hosting provider.

Once you have access to the repository you'd like to use, you can start creating Swimm docs.

2.2 Install the Swimm IDE Plugin​

Download the Swimm plugin for your favorite IDE to access Swimm docs directly from your code editor. Go to your extension marketplace and search for "Swimm", or use the links below:

Part 3: Using Swimm (For All Users)​

3.1 Why Use Swimm?​

Traditional documentation solutions are often difficult to maintain, and engineers spread content across multiple tools, making it difficult to find and trust information when code changes regularly.

Swimm is designed to make it easy to create, maintain, and share documentation with your team. Swimm Docs are markdown files that contain your documentation content and are stored in a git repository.

3.2 Working with Documentation​

Create and Edit Documents​

To create a new Swimm doc, click on the Document button in the IDE plugin. This will open a new markdown file in your IDE within the .swm directory.

• If you do not have any Swimm documents in your repository, the plugin will create the .swm directory for you.
• If you git pull a repository with Swimm docs, the plugin will recognize the existing .swm directory and display the docs in the plugin.

Give Your Document a Title​

Start by giving your document a title. Our recommendation is to be as descriptive as possible - How to post analytics is a better title than Analytics, as the former tells the reader what they will learn from reading the doc.

Add Content to Your Document​

Write with Markdown to add content to your Swimm doc. We encourage writers to take advantage of our Editor commands to make writing easier and code-couple your documentation to your codebase.

Any time you link code to your documentation, Swimm will automatically update the code snippets in your docs when the code changes. This ensures that your documentation is always up-to-date.

1. Type /Code snippet and press enter

2. Select snippet from codebase and click Add to Doc

3: Save Swimm doc

Here is a list of important Swimm commands:

Discoverability of Docs​

Swimm makes it easy to find documentation in your IDE in two ways:

1. Plugin Search​

The search bar is located at the top of the plugin.

2. Code Snippet Waves 🌊​

Swimm makes it easy for documentation to find you. When you're in a file that references a code snippet in a Swimm doc, hover over the blue icon in the gutter to see an option to open the documentation.

Auto-sync and Doc Maintenance​

When you make changes to your code, Swimm will notify you that code snippets in your docs are out of date.

1. Click Status to Verify Your Documents​

If your code has changed and you haven't updated your Swimm docs, you'll see "⚠️ Review required" status. Click on the affected doc(s) to update outdated code-coupled elements.

2. Open Your Affected Document, Reconcile Changes and Save​

3. Verify Docs Are Up-to-Date and Commit to Repository​

3.3 Codebase Explanations​

Swimm Explore helps you understand unfamiliar code by analyzing your repository structure, discovering modules and components, and using AI to generate comprehensive artifacts based on that analysis.

Step 1: Analyze Your Repository​

In your Swimm IDE plugin, click on the Analyze Repo button to start the exploration process. Swimm will begin analyzing your codebase structure.

Step 2: Discovering Modules​

Swimm will automatically scan through your repository using static analysis to discover modules, components, and key areas of your codebase.

Step 3: Analysis Complete​

Once the analysis is complete, you'll see a confirmation that your repository has been successfully analyzed.

Step 4: View Discovered Modules​

Browse through the modules and components that Swimm has discovered in your codebase. Each module represents a logical grouping of functionality.

Step 5: Expand a Module​

Click on any module to expand it and see the details, files, components, and the call tree showing where it's used within your codebase.

Step 6: Module Actions​

Each module provides several options to help you understand and document the code:

Step 7: Generate Module Explanation​

Select the Explain option. AI will process Swimm's static analysis to generate a comprehensive explanation for the module.

Step 8: Explore and Save Documentation​

Review the generated documentation which includes technical explanations, business rules, code-coupled diagrams, and flow documentation. You can edit, refine, and save it as a Swimm doc for your team to use.

Module Explanation Flow​

See the entire module explanation workflow in action:

3.4 Advanced Features​

Doc Rules​

Doc rules are a way to enforce documentation standards across your organization. You can create rules that surface knowledge to your fellow engineers as they type inside files within the IDE.

Swimm's Rules feature links your codebase to relevant information using Regex rules.

When a rule is triggered, a notification in the form of blue waves that underline the code will appear as you finish typing, prompting the user to hover and read the relevant information and linked Swimm doc, if attached.

Creating Rules​

1. Create a new rule: In your IDE, open Swimm's plugin. Here, you'll find the Rules button. Click on it to start creating a new rule.

2. Choose the relevant Swimm document (Optional): This document will be linked with your regex rule and will be displayed whenever the rule's conditions are met in the code.

3. Enter rule details:

   • Title - will be shown in the Rules view to identify this rule.
   • Description - will be shown when the user hovers over the marked code.
   • Restrict rules to paths or types - you can restrict the rule to match only to specific paths or file types.
   • Regex - the regex that should be met for the rule to apply.

(Optional) Case-Insensitive Rules​

If you want your rule to be case-insensitive, click on the Ignore case checkbox.

Save, Test and Commit​

1. Save and test: Click Apply, and you will be able to see the highlighting in your code. We recommend testing in your IDE to see that the rule works the way you expect. Open a file and type to match the Regex pattern you defined. You should see the Rule match with the text you typed. If it doesn't, you may need to adjust the Regex pattern.

2. Commit: Rules are stored in your code under the .swm/rules.json file. Commit and push your changes to this file. Once your colleagues pull the latest version which includes your changes, everyone will share the same rules.

Playlists (Swimm Web App)​

Playlists are a way to group related Swimm docs and external resources together. You can create a playlist for a specific feature, project, or team, and share it with your team.

Create a Playlist​

1. Select your repository and Create your Playlist.

2. In the Intro section, give your playlist a name and description. Add Swimm docs you'd like to include.

If you have separate Playlists that relate to each other, you can nest Playlists within Playlists.

3. Completed Playlists can be accessed within the repository in Swimm

Organize Docs (Swimm Web App)​

Folders​

Folders allow you to create a hierarchy, by grouping related documents or playlists. Every doc, playlist and folder in the repository can have a parent folder.

Learn more about Folders.

Tags​

You can put tags on each doc, and then filter the tags in your repos to quickly find relevant documents. Tags can be assigned to local drafts, as well as docs that have been committed to the repo. When a tag is created, it can be used across all of your workspace repositories.

3.4 Best Practice Guides​

Here are a list of Swimm guides to download and share with your team.