Sign In

1. Open Datatoc.
2. Select Sign in with Microsoft.
3. Choose the work, school, or invited guest account that has Datatoc access.
4. Complete any multifactor authentication required by your organization.
5. Allow the sign-in window to return control to Datatoc.

Create or Open a Workspace

After sign-in, create a workspace in a folder where your Windows account has read and write access. A workspace can contain datasets, metadata, saved scripts, cleaning outputs, visualizations, and conversation records.

Recommended locations: a user Documents folder or an organization-approved synchronized folder. Do not place a workspace under the Datatoc installation directory or another read-only system location.

What Stays Local

• Imported source files retained by the workspace.
• Workspace and project metadata.
• Saved scripts and reusable analysis assets.
• Cleaning outputs, generated plots, and exported results.

What Uses Datatoc Cloud

When you request an AI or code-execution operation, Datatoc sends the data and context required to the organization-configured Datatoc Cloud service. The service authenticates the request and uses Microsoft Foundry and Azure Container Apps Dynamic Sessions.

Account Not Accepted

Your administrator must assign your Microsoft account to an allowed Datatoc app role. External Microsoft accounts must be invited to the organization's tenant first.

Connection Problems

1. Check the computer's internet connection.
2. Select Try again in Datatoc.
3. Close and reopen Datatoc if the message continues.
4. Ask your administrator whether other users are affected.
5. Send the approximate time and a screenshot to support, without including confidential dataset content.

Overview

Datatoc is a desktop application that connects to a cloud API that you or your IT team deploys and controls on your Azure subscription. No Datatoc infrastructure handles your data — everything runs within your Azure tenant.

Components

Key Principles

• The desktop installer contains one public Datatoc Cloud API URL.
• Microsoft Entra ID authenticates users and supplies Datatoc app roles in access tokens.
• The Cloud API uses a managed identity to reach Foundry and Dynamic Sessions.
• No Azure service key is placed in the desktop application.
• Each authenticated operation receives a separate request context and Dynamic Sessions sandbox.
• Workspace files, saved scripts, and outputs remain in the local folder selected by the user.

Deployment Flow

1. Create Azure prerequisites (subscription, resource group, naming)
2. Configure Microsoft Entra ID (app registrations, roles)
3. Create Microsoft Foundry project and model deployment
4. Configure Azure Container Apps Dynamic Sessions pool
5. Build and push Datatoc Cloud image to Azure Container Registry
6. Deploy Datatoc Cloud API to Container Apps
7. Package desktop with the Cloud API URL and distribute to users

What Is Local (Never Leaves the Device)

• All workspace files and folders selected by the user.
• Saved scripts and Standard Analysis templates.
• Generated charts, cleaning outputs, and exported reports.
• Workspace and project metadata (dataset names, column lists, settings).

What Is Sent to Datatoc Cloud

• The specific data sample or dataset submitted for an AI or code-execution operation.
• The user's natural-language prompt for that operation.
• A Microsoft Entra access token — used only to authenticate the request.

Authentication & Authorisation

• Sign-in is handled by Microsoft identity (Entra ID) — Datatoc never sees your password.
• Role-based access control (RBAC) is enforced at the Cloud API using app roles.
• Each request is independently authenticated — there are no long-lived sessions in the Cloud API.

Isolation

• Each code-execution request runs in a dedicated Azure Container Apps Dynamic Sessions sandbox.
• Sandboxes are destroyed after the request completes.
• No sandbox can access another user's data or sandbox.

Customer Responsibilities

• Configuring the Azure region, network controls, and retention settings.
• Managing user access via Entra app roles.
• Data residency decisions — where your Azure Container Apps and Foundry are deployed.
• Backups and data-protection policy for local workspace folders.

Before You Begin

• An Azure subscription with sufficient quota in the selected region.
• Permissions to create resource groups, register apps in Entra, and create Container Apps, Foundry projects, and Container Registries.
• A supported region for Azure AI Foundry and Azure Container Apps Dynamic Sessions.

Resource Group

Create a dedicated resource group for all Datatoc resources. Using a single resource group makes it easy to manage costs, apply policy, and clean up resources.

$RESOURCE_GROUP = "rg-datatoc-prod"
$LOCATION = "eastus"

az group create `
  --name $RESOURCE_GROUP `
  --location $LOCATION

Naming Conventions

App Registrations Required

Configure the Cloud API Registration

1. Open Microsoft Entra admin center › App registrations › New registration.
2. Name it Datatoc Cloud API.
3. Set supported account types to Accounts in this organizational directory only.
4. Under Expose an API, set an Application ID URI (e.g. api://<client-id>).
5. Add a scope named access_as_user (admin and user consent).
6. Under App roles, add Datatoc.User and Datatoc.Admin.

Configure the Desktop Registration

1. Create a second app registration named Datatoc Desktop.
2. Under Authentication › Mobile and desktop applications, add http://localhost as a redirect URI.
3. Set Allow public client flows to Yes.
4. Under API permissions, add the access_as_user scope from the Cloud API registration.

Assign Users

Go to Enterprise applications › Datatoc Cloud API › Users and groups and assign users or groups to the Datatoc.User or Datatoc.Admin role.

Create a Foundry Project

1. Open Azure AI Foundry in the Azure Portal.
2. Create a new Hub in a supported region (e.g. East US, Sweden Central).
3. Under the hub, create a new Project for Datatoc.

Deploy a Model

1. In your Foundry project, go to Models + endpoints › Deploy model.
2. Select a model (e.g. gpt-4o or gpt-4o-mini).
3. Note the deployment name — this is the value you set in the Cloud API environment variable DATATOC_MODEL_DEPLOYMENT_NAME.
4. Review token quota and adjust as needed for your team size.

Grant Managed Identity Access

The Datatoc Cloud API uses a managed identity to call Foundry. Assign the Foundry User role on the Foundry project to the Container App's managed identity.

What Dynamic Sessions Does

Dynamic Sessions provides isolated, ephemeral Python execution sandboxes for each Datatoc analysis request. Each sandbox is destroyed after the request completes, ensuring complete isolation between users and requests.

Create a Session Pool

1. In the Azure Portal, go to your Container Apps Environment.
2. Select Dynamic sessions › Session pools.
3. Create a new pool with PythonLTS code interpreter.
4. Configure maximum concurrent sessions based on your team size.
5. Note the management endpoint — this is the value for DATATOC_ACA_SESSION_POOL_ENDPOINT.

Grant Managed Identity Access

Assign the Azure ContainerApps Session Executor role on the session pool to the Datatoc Cloud API's managed identity.

Create Azure Container Registry

$ACR_NAME = "acrdatatocdprod"
$RESOURCE_GROUP = "rg-datatoc-prod"

az acr create `
  --name $ACR_NAME `
  --resource-group $RESOURCE_GROUP `
  --sku Basic `
  --admin-enabled false

Build and Push the Cloud Image

# Log in to ACR
az acr login --name $ACR_NAME

# Build and push image using ACR Tasks (no local Docker required)
az acr build `
  --registry $ACR_NAME `
  --image datatoc-cloud:latest `
  --file Dockerfile.cloud .

Grant Container App Pull Access

Assign the AcrPull role on the registry to the Datatoc Cloud API's managed identity. This allows the Container App to pull images without storing credentials.

Required Environment Variables

Deploy the Container App

az containerapp create `
  --name ca-datatoc-prod `
  --resource-group $RESOURCE_GROUP `
  --environment $CONTAINER_APP_ENV `
  --image "$ACR_NAME.azurecr.io/datatoc-cloud:latest" `
  --target-port 8000 `
  --ingress external `
  --min-replicas 1 `
  --max-replicas 10 `
  --system-assigned

Verify Deployment

$APP_URL = "https://<your-container-app-fqdn>"

# Health check
Invoke-RestMethod "$APP_URL/api/v1/health"

# Bootstrap (returns sign-in config)
Invoke-RestMethod "$APP_URL/api/v1/bootstrap" | Format-List

Embed the Cloud API URL

The Datatoc desktop installer contains one public Datatoc Cloud API URL. Update the build configuration to point to your Container App FQDN before building the installer:

DATATOC_CLOUD_URL=https://<your-container-app-fqdn>

Build the Installer

1. Run the backend build to bundle Python dependencies.
2. Run the Electron builder to produce the .exe installer.
3. Validate the installer signature and checksum before distribution.
4. Test installation in both current-user and all-users modes.
5. Verify Microsoft sign-in from a standard user account.

Validate Before Rollout

• Sign in from a standard user account (not administrator).
• Create a workspace and run a simple analysis.
• Confirm workspace files are written to the expected user-writable location.
• Confirm the Cloud API returns correct health and bootstrap responses.

Adding a New User

1. Go to Entra admin center › Enterprise applications › Datatoc Cloud API.
2. Select Users and groups › Add user/group.
3. Select the user or group and assign the Datatoc.User or Datatoc.Admin role.
4. The user must sign out and sign in again to receive the updated token.

Removing a User

1. Remove the user from the enterprise application role assignment in Entra.
2. Optionally revoke active sessions via Entra's session management.

External Users (Guests)

1. Invite the external user to your Entra tenant.
2. Have them accept the invitation.
3. Assign them to the appropriate Datatoc app role.

Monitoring

• Use Container Apps Log Analytics for API request logs and errors.
• Monitor Foundry usage and quotas in the Azure AI Foundry portal.
• Set up Azure Monitor alerts for Container App replica scaling and error rates.

Welcome Screen Shows a Connection Message

For Users

1. Confirm internet access.
2. Select Try again.
3. Close and reopen Datatoc.
4. Contact your administrator if other users are affected.

For Administrators

$APP_URL = "https://<datatoc-cloud-api-hostname>"
Invoke-RestMethod "$APP_URL/api/v1/health"
Invoke-RestMethod "$APP_URL/api/v1/bootstrap" | Format-List

Microsoft Sign-in Does Not Open

• Confirm the installer was created from the current desktop source.
• Confirm dist/preload/preload.cjs is packaged.
• Confirm the BrowserWindow loads preload.cjs.
• Rebuild and reinstall the corrected package.

Account Does Not Exist in Tenant (AADSTS)

1. Confirm the user selected the correct work or school account.
2. Invite external accounts as a guest if required.
3. Confirm the invitation was accepted.
4. Assign the user or group to the Datatoc Cloud API enterprise application role.
5. Sign out and sign in again.

Redirect URI Mismatch (AADSTS50011)

1. Open Entra admin center › App registrations › Datatoc Desktop › Authentication.
2. Under Mobile and desktop applications, add the redirect URI: http://localhost.
3. Set Allow public client flows to Yes.
4. Save, wait a few minutes, and try again.

User Signs In but Receives 403

• Confirm the user has Datatoc.User or Datatoc.Admin assigned on the Cloud API enterprise application.
• Confirm DATATOC_ENTERPRISE_REQUIRED_ROLES uses the same exact values.
• Sign out and sign in after role assignment to get a new token.

Cloud API Returns 404

• Use the stable Container App application FQDN, not a revision URL.
• Confirm external ingress is enabled and target port is 8000.
• Confirm the active revision uses the Datatoc cloud image.

Foundry Permission Error

An error mentioning Microsoft.CognitiveServices/accounts/AIServices/agents/write means the Cloud API managed identity lacks the required Foundry data-plane permission. Assign Foundry User to that identity on the Foundry project.

ConnectionResetError During AI Operation

Usually means a remote service, proxy, or firewall closed the connection. It can succeed on retry when the cause is temporary. Check Container App, Foundry, and session-pool logs. Review proxy idle timeouts.

Information to Collect for Support

• Datatoc version and installer filename.
• Windows version and installation mode (current-user or all-users).
• Approximate time and timezone of the failure.
• Friendly UI message and screenshot.
• Cloud API health and bootstrap result (with tenant values redacted).
• Container App revision and image tag.
• Relevant service-log exception and request correlation ID.

Local Development Setup

1. Clone the Datatoc repository.
2. Set up the isolated backend build environment with the pinned requirements-backend.txt.
3. Configure environment variables (tenant ID, client ID, Foundry endpoint, session pool endpoint).
4. Run the Cloud API locally: uvicorn app.main:app --reload --port 8000.
5. Point the desktop app to http://localhost:8000 for local testing.

Release Validation Checklist

• Run all unit and integration tests.
• Build and test the installer in current-user mode.
• Build and test the installer in all-users mode.
• Verify Microsoft sign-in from a standard account.
• Create a workspace and run a basic analysis end-to-end.
• Verify workspace files are written to the correct user-writable path.
• Run the upgrade flow from the previous release.
• Run the uninstall flow and verify workspace folders are not deleted.

Common Development Issues