Overview
This page provides a comprehensive guide to the ToolBox Setup page, which is the central configuration hub for Erik's ToolBox. All major integrations and features are configured here, including Program Storage (Azure Blob Storage or GitHub), Remote ToolBox connections, AI-assisted coding, and GitHub data integration.
Accessing the Setup Page
The ToolBox Setup page is where you configure all global settings for Erik's ToolBox. To access it:
- Open the Erik's ToolBox main page.
- Choose the Setup action in the action bar.
Alternatively, you can search for "ToolBox Setup" in the Business Central search bar.
Permission Requirements
The ToolBox Setup page requires the SUPER permission set in Business Central. If you attempt to open the Setup page without the SUPER role, an error message is displayed and access is denied. This restriction ensures that only administrators can modify the global configuration that affects all ToolBox users in the environment.
The Setup page reads from and writes to the ToolBox Setup table. Because this table has the DataPerCompany = false property, the configuration applies to all companies within the same Business Central environment. You only need to configure the ToolBox once per environment.
Setup Page Layout
The Setup page is organized into configuration groups, each controlling a different area of ToolBox functionality. The following sections describe each group, its fields, and its purpose.
General
The General group contains basic environment identification settings.
| Field | Description |
|---|---|
| NickName | A friendly name for this environment. This name is displayed in the ToolBox title bar, making it easy to identify which environment you are working in when you have multiple environments open. |
When to Use
Set the NickName when you work with multiple Business Central environments (for example, production, staging, and development). A clear, descriptive name helps you avoid accidentally running scripts or modifying data in the wrong environment.
Example
If your organization has three environments, you might configure the following NickNames:
- Production:
PROD - Contoso - Staging:
STAGING - Contoso - Development:
DEV - Contoso
The NickName appears in the ToolBox editor title, so you can always see at a glance which environment your session is connected to.
Program Storage
The Program Storage group controls where shared programs are synchronized so they can be shared across multiple Business Central environments. You choose one backend — Azure Blob Storage or GitHub — or turn synchronization off entirely.
| Field | Description |
|---|---|
| Program Storage | Selects where shared programs are stored: None (no synchronization), Azure Blob Storage, or GitHub. The remaining fields change depending on this choice. |
Only programs marked as Shared are synchronized. Each environment writes its own programs to a location keyed by its NickName, and when you open the ToolBox it pulls the other environments' programs and shows them as read-only remote programs. Set a distinct NickName per environment first, or synchronization is skipped.
Synchronization runs automatically: programs are pushed when you save, and pulled when you open the ToolBox.
Legacy setting: Earlier versions used a Use Azure Storage toggle. That toggle is migrated automatically — if it was on, Program Storage is set to Azure Blob Storage the next time the Setup record is read, and the old toggle is cleared.
Azure Blob Storage
When Program Storage is set to Azure Blob Storage, these fields appear:
| Field | Description |
|---|---|
| Azure Storage Account | The name of your Azure Storage account as it appears in the Azure portal (for example, contosostorage). |
| Azure Access Key | The shared access key for the storage account, found in the Azure portal under the account's Access Keys section. Either key1 or key2 can be used. |
The ToolBox creates and manages a toolboxprograms container automatically; you do not create containers manually. Each environment's shared programs are written to a single blob named after its NickName.
GitHub
When Program Storage is set to GitHub, these fields appear:
| Field | Description |
|---|---|
| GitHub Account Name | The GitHub account (user or organization) that owns the repository used for program storage. |
| GitHub Personal Token | A personal access token that grants read/write access to the repository. Used as a bearer token against the GitHub GraphQL API. |
| GitHub Repository | The repository where programs are stored. |
| GitHub Branch | The branch to use. Leave blank to use the repository's default branch. |
Programs are stored as individual .al files under a Programs/<NickName>/ folder — one file per shared program — alongside a small .toolbox.json file recording the environment's tenant, environment name, and nickname. Because each environment uses its own nickname sub-folder, several environments can share one repository and pull each other's programs. The target repository must already contain at least one commit; the ToolBox cannot commit to a completely empty repository.
Not the same as Data in GitHub. Program storage in GitHub is a separate feature from the Data in GitHub table-data feature. It has its own account, token, repository, and branch fields, and can point at a different repository.
Purpose
Program synchronization lets you share and back up ToolBox scripts across environments — for example, authoring in a development environment and having the same shared programs appear in staging and production. Use it to:
- Share scripts across development, staging, and production environments
- Back up your ToolBox programs to the cloud or to version control
- Collaborate with team members who work in different environments
Choosing GitHub additionally gives you version history for every shared program, since each save is committed as one .al file per program.
Prerequisites
For Azure Blob Storage you need an Azure Storage account with Blob Storage and a valid access key. For GitHub you need a GitHub account, a repository with at least one commit, and a personal access token with repository read/write (repo) permissions. In both cases the Allow HttpClient Requests setting must be enabled for the ToolBox extension in Business Central's Extension Management.
Configuration Steps
- Open the ToolBox Setup page and set a distinct NickName for the environment.
- Set Program Storage to Azure Blob Storage or GitHub.
- Fill in the fields that appear for the chosen backend (Azure account and access key, or the
GitHub account, token, repository, and optional branch).
- Close the Setup page. Shared programs are pushed on save and pulled when the ToolBox opens.
Remote ToolBox
The Remote ToolBox group configures OAuth2 credentials for connecting to another Business Central environment. This enables the Remote Packages feature, which allows you to transfer data between environments and tenants.
| Field | Description |
|---|---|
| Remote Tenant ID | The Azure Active Directory (Azure AD) tenant ID of the remote Business Central environment. You can find this in the Azure portal under Azure Active Directory > Properties > Tenant ID. |
| Remote Application ID | The OAuth2 client (application) ID for the app registration that has been granted access to the remote Business Central environment. This is created in the Azure portal under App Registrations. |
| Remote Secret | The OAuth2 client secret associated with the Remote Application ID. This secret is generated in the Azure portal under the app registration's Certificates & Secrets section. |
Purpose
The Remote ToolBox connection enables the Remote Packages feature, which allows you to:
- Copy table data from one Business Central environment to another
- Transfer data between different tenants
- Migrate data during environment upgrades or tenant changes
- Synchronize reference data across environments
Prerequisites
To configure a Remote ToolBox connection, you need:
- An Azure AD app registration in the remote tenant with appropriate Business Central API permissions
- The app registration must be granted admin consent for the required permissions
- The app registration must have a client secret that has not expired
- The remote Business Central environment must have the ToolBox installed and configured
Configuration Steps
- Open the ToolBox Setup page.
- Enter the Remote Tenant ID of the target environment.
- Enter the Remote Application ID from the Azure AD app registration.
- Enter the Remote Secret (client secret) from the app registration.
- Close the Setup page.
Once configured, you can use the Remote Packages feature from the ToolBox main page to initiate data transfers to and from the remote environment.
Security Considerations
- Store the Remote Secret securely. Anyone with this secret and the application ID can authenticate to the remote environment.
- Use app registrations with the minimum necessary permissions.
- Rotate the client secret periodically according to your organization's security policies.
- Consider using separate app registrations for different source environments to maintain clear audit trails.
AI Providers
The AI agents are not configured in a group on the Setup page but on the AI Providers page, opened with the AI Providers action in the action bar. The page belongs to the AL AI Services app and is shared with other Hougaard apps that host agents.
| Field | Description |
|---|---|
| Provider | The AI service: Azure Open AI, ChatGPT Open AI, Anthropic (Claude), LM Studio, Google Gemini, xAI Grok, Mistral, DeepSeek, Moonshot Kimi, Alibaba Qwen, Zhipu GLM, or MiniMax. One row per provider. |
| Endpoint | The provider's chat endpoint URL. |
| Access Key | The API key, shown masked. The drill-down opens the provider's key console. Empty for LM Studio. |
| Model | The model name (the deployment name for Azure). Blank uses the ToolBox default for the provider. |
| ToolBox Agent | Turn on for the row the ToolBox Agent (Interactive Code) and the SQL Agent (SQL Workbench) should use. |
Purpose
With a provider row selected, an agent FactBox appears next to the editor on the Interactive Code page and on the SQL Workbench. The agents write, check, run, and explain programs and SQL statements by acting on the editor through tools, look up your data model, and manage saved programs and statements. Conversations are saved and can be resumed.
Legacy Fields
Versions before 5.0 had a Coding Agent Setup group on this page. Its fields are obsolete and hidden; their values are not migrated. Enter the provider on the AI Providers page instead.
For endpoints, keys, and per-provider notes, see AI Agents Setup.
GitHub Integration
The GitHub Integration group configures the connection to GitHub for the Data in GitHub feature, which provides version-controlled data management for Business Central tables.
| Field | Description |
|---|---|
| GitHub Account Name | Your GitHub username. This is the account that owns or has access to the repositories where ToolBox data will be stored. |
| GitHub Personal Token | A personal access token (PAT) for the GitHub API. This token must have repository read and write permissions. You can generate one from GitHub's Settings > Developer settings > Personal access tokens. |
| JSON Format | Controls how data is serialized to JSON when pushed to GitHub. Choose between Verbose (human-readable, larger file size) and Compact (smaller file size, less readable). |
| Empty Tables Before Pull | When enabled, the ToolBox clears all existing data in the target table before pulling data from GitHub. When disabled, pulled data is merged with existing records. |
| Monitor Start Time | The time of day when the change monitoring process begins. The ToolBox monitors tables for changes and can automatically commit those changes to GitHub at this time. |
Purpose
The Data in GitHub feature provides version control for Business Central table data. With this integration, you can:
- Store table data in GitHub repositories as JSON files
- Track changes to data over time using Git version history
- Roll back to previous data states when needed
- Share reference data across teams using standard Git workflows
- Monitor tables for changes and automatically commit updates
Prerequisites
To use GitHub integration, you need:
- A GitHub account (personal or organizational)
- A personal access token with
reposcope permissions - The Allow HttpClient Requests setting enabled for the ToolBox extension
- A repository where the ToolBox can read from and write to
Configuration Steps
- Open the ToolBox Setup page.
- Enter your GitHub Account Name.
- Enter your GitHub Personal Token.
- Select the preferred JSON Format (Verbose or Compact).
- Set Empty Tables Before Pull based on your data management strategy.
- Set the Monitor Start Time to the time when automatic change monitoring should begin.
- Close the Setup page.
JSON Format Options
| Format | Description | When to Use |
|---|---|---|
| Verbose | Produces human-readable JSON with full field names and indentation | When you need to review data changes in GitHub diffs, or when file size is not a concern |
| Compact | Produces minimized JSON with shorter output | When you are storing large amounts of data and want to minimize repository size |
Best Practices
- Use a dedicated GitHub account or a machine account for ToolBox data operations rather than a personal developer account.
- Create a separate repository for ToolBox data to keep it isolated from source code.
- Set the Monitor Start Time to a period of low system activity to minimize performance impact.
- Review the Empty Tables Before Pull setting carefully. Enabling it ensures a clean pull but destroys any local data not present in the GitHub repository.
Configuration Data Storage
All configuration settings are stored in the ToolBox Setup table. Key characteristics of this table:
| Property | Value | Implication |
|---|---|---|
| DataPerCompany | false | Settings apply to all companies in the environment |
| Scope | Global | A single configuration record shared across the environment |
Because the configuration is global, any changes you make to the Setup page affect all users and all companies within the Business Central environment. Coordinate with other administrators before making changes, especially to Program Storage or Remote ToolBox settings that affect synchronization.
Tips and Best Practices
- Configure the NickName field immediately after installation to clearly identify your environment in the ToolBox editor title.
- Keep API keys and secrets secure. The Setup page is protected by the SUPER requirement, but you should also follow your organization's key management policies.
- Test integration settings in a development or staging environment before applying them to production.
- Document your configuration settings externally, especially the Azure AD app registration details and GitHub token permissions, so they can be reproduced if needed.
- Review your Azure Storage access keys and GitHub personal tokens periodically and rotate them according to your security policies.
- When configuring multiple environments for program sharing, point them all at the same Program Storage backend (the same Azure Storage account, or the same GitHub repository) and give each a distinct NickName so they can pull each other's shared programs.