Configuration Server

The configuration server is an ordinary web server in your intranet. It serves one ZIP archive per configuration. Any web server that can serve files from a folder will do.

What AI Studio requests

AI Studio builds the address from the server address and the configuration ID that you store on the device. With the server address https://intranet.example.org:30100/ai-studio/configuration and the ID 9072b77d-ca81-40da-be6a-861da525ef7b, it requests:

https://intranet.example.org:30100/ai-studio/configuration/9072b77d-ca81-40da-be6a-861da525ef7b.zip

• A trailing slash in the server address doesn't matter.
• The ID is always in lowercase, even when you stored it in uppercase. Name the files on your server in lowercase, or make your server ignore the case.
• Each configuration is requested on its own. When one server fails, AI Studio still loads the others.

When AI Studio downloads

• At every start, AI Studio downloads every configuration.
• Every 16 minutes, it sends a GET request for each configuration but reads only the response headers. When the ETag differs from the one of its current version, it downloads the archive. When the ETag is the same, it downloads nothing.
• Your server must send an ETag. Without one, AI Studio can't detect a change, and devices only receive a new version of your configuration at their next start. Most web servers send ETags for static files by default.
• When the server can't be reached or the download fails, AI Studio keeps the version it already has. A device that never received a configuration activates it with the first successful download.
• The timeout for these requests is the same as for all external requests of AI Studio. You can set it with DataApp.HttpClientTimeoutSeconds.

What the archive contains

9072b77d-ca81-40da-be6a-861da525ef7b.zip
├── plugin.lua                  ← your configuration plugin, ID = 9072b77d-…
├── icon.lua                    ← its icon, an SVG
└── translation-assistant/
    └── plugin.lua              ← an assistant plugin with an ID of its own

• The archive must contain at least one plugin.lua. AI Studio loads every plugin.lua it finds in the tree.
• Only the configuration plugin carries the configuration ID. Every other plugin has its own ID.
• An archive doesn't need a configuration plugin at all. One that only ships an assistant plugin is fine.
• The icon must be an SVG. AI Studio shows it isolated from the app, so set the colors inside the SVG itself. Your organization needs the rights to every icon it ships.
• AI Studio replaces the previous version of a configuration only when the new archive was downloaded and extracted completely.

Securing the server

• Keep the server in your intranet. It must not be reachable from the internet.
• Switch off directory listings. A configuration may contain API keys, even if encrypted, and the addresses of internal services. Each user should only know the IDs of their own configurations. Otherwise, somebody might use another ID to reach resources meant for others.
• Use HTTPS. With a certificate from your own certificate authority, see Your own certificate authorities below.

Example with Caddy

Caddy is an open-source web server. This Caddyfile serves the archives from the folder /srv/ai-studio/config with the TLS certificate from /srv/tls, hides the folder's content, and answers every other request with 404:

{
    # Disable logging:
    log {
        output discard
    }

    # Disable automatic HTTPS redirection:
    auto_https off
}

intranet.example.org:30100 {
    # Load the TLS certificate:
    tls /srv/tls/cert_webserver.pem /srv/tls/key_webserver.pem

    # Serve the configuration archives:
    handle_path /ai-studio/configuration/* {
        file_server {
            root /srv/ai-studio/config

            # Disable directory listings:
            browse false
        }
    }

    # Answer all other requests with 404:
    handle {
        respond "Not Found" 404
    }
}

Caddy sends ETags for static files on its own.

Your own certificate authorities

AI Studio trusts the certificate authorities of the operating system. When your servers use certificates of your organization's own certificate authority, and the operating system doesn't trust it, AI Studio can use an extra bundle of root certificates. This matters most for Flatpak, where AI Studio can't read the certificates of the host. It applies to self-hosted AI providers, embedding and transcription providers, ERI servers, mail servers, and the configuration server.

The bundle is a PEM file with one or more root certificates:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

AI Studio uses it only for the hosts you allow. It doesn't switch off the verification of certificates: AI Studio first checks a certificate as usual. Only when the check fails because the chain ends at an unknown root does it try again with your bundle. Wrong host names, expired certificates, and other invalid chains are still rejected. The endpoints of cloud providers, such as OpenAI or Google, never use your bundle.

You can provide the bundle in three ways. AI Studio uses the first one it finds:

1. A policy file named external_http_custom_root_certificates.yaml, in the same folder as the other policy files of your operating system (see the deployment page of your operating system). AI Studio reads it when it starts. Because it is available before the first download, it also works for the configuration server itself.

   enabled: true
   bundle_path: "/app/etc/MindWorkAI/company-root-cas.pem"
   allowed_hosts: "*.intra.example.org;eri.example.org"

   With enabled: false, you switch off extra root certificates and AI Studio ignores the two other ways.

2. Environment variables, set before AI Studio starts. A variable you leave out falls back to the setting in AI Studio, which your configuration plugin may manage:

   MINDWORK_AI_STUDIO_EXTERNAL_HTTP_CUSTOM_ROOT_CERTIFICATES_ENABLED=true
   MINDWORK_AI_STUDIO_EXTERNAL_HTTP_CUSTOM_ROOT_CERTIFICATE_BUNDLE_PATH=/path/to/company-root-cas.pem
   MINDWORK_AI_STUDIO_EXTERNAL_HTTP_CUSTOM_ROOT_CERTIFICATE_ALLOWED_HOSTS=*.intra.example.org;eri.example.org

3. Your configuration plugin. It only takes effect after the first download, so it can't help with the configuration server itself:

   CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificatesEnabled"] = true
   CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificateBundlePath"] = "/path/to/company-root-cas.pem"
   CONFIG["SETTINGS"]["DataApp.ExternalHttpCustomRootCertificateAllowedHosts"] = { "*.intra.example.org", "eri.example.org" }

Allowed hosts are host names only: no scheme, no port, no path. A pattern is either an exact host, such as eri.intra.example.org, or a wildcard for exactly one more label: *.intra.example.org covers eri.intra.example.org, but neither intra.example.org nor a.eri.intra.example.org. Separate several hosts with ; or ,. AI Studio ignores invalid patterns and logs a warning.

In a Flatpak, you can also set SSL_CERT_FILE or SSL_CERT_DIR in the launch environment to a bundle or a folder of certificates that AI Studio can read inside the sandbox.

Where to go next

• How Central Configuration Works
• Enterprise IT