Frequently asked questions
This topic covers the most common questions about Boomi Companion, along with tips and tricks to help you get the most out of the plugin.
Getting started
What do I need before using Boomi Companion?
You need three things: an AI coding agent, an IDE or terminal, and a Boomi Platform account.
On the Boomi side, you need your platform username, an API token, and your account ID. Optionally, you can provide an environment ID and runtime ID if you want Boomi Companion to deploy and test your integrations.
How do I install the Boomi Companion plugin?
- Launch Claude Code and run
/plugin marketplace add OfficialBoomi/boomi-companionto add the Boomi Companion marketplace. - Run
/plugin, navigate to Marketplaces, and select boomi-companion. - Select Browse plugins and install the plugin you want, for example,
bc-integration. You can install any Boomi Companion plugin using these same steps. - Run
/reload-pluginsto load it. You can enable auto-updates through the same/pluginmenu so you always have the latest version.
Which Boomi environment should I use with Boomi Companion?
Use a development or test environment, not production. Boomi Companion deploys and tests processes against whichever environment and runtime you configure in your .env file using BOOMI_ENVIRONMENT_ID and the runtime ID. Pointing to a non-production environment keeps AI-generated components and test executions isolated from live data and production systems.
Build, deploy, and validate in your development or test environment first. Once you are satisfied with the result, promote the process to production through your organization's normal release process, such as Boomi's environment promotion workflow.
What is the difference between the template workspace and a project folder?
The template workspace is your reusable starting point; it holds your platform credentials, directory structure, and any custom instructions you have configured. A project folder is a fresh copy of that template for a specific piece of work. Each time you start a new effort, create a new project folder and run /freshies to initialize it from your template. This keeps projects isolated while letting you maintain a single source of truth for credentials and preferences.
How do I update the Boomi Companion plugins for Claude?
If you enable auto-updates during installation, the plugin updates automatically. You can also manually check for updates through the /plugin menu by navigating to Marketplaces and selecting boomi-companion.
General
What can Boomi Companion do?
With the Boomi Companion plugins/skills installed, ask your AI agent, "What are bc-integration's capabilities?" It can describe its current capabilities directly.
What does Boomi Companion not support yet?
Boomi Companion does not yet support Flow, API management, Boomi for SAP, API Control plane, Task Automation, Connect, Knowledge Hub and Runtime Management. It currently covers integration processes, including Tech connectors, maps, scripts, profiles, and EDI.
When Boomi Companion cannot build something directly, you can complete that step in the Boomi Platform UI and then provide Boomi Companion with the component ID or a link. From there, it can pull the component in and continue building.
Does Boomi Companion replace the Boomi Platform UI?
No. Boomi Companion is complementary tooling, not a replacement for the platform. It creates and manages components through the Platform API, but you can always view, verify, and manually edit anything it builds in the Boomi UI. Many developers use both side by side.
Can I use Boomi Companion with AI tools other than Claude Code?
Yes. Boomi Companion runs on Agent Skills, an open standard that works with multiple AI agents, including OpenAI Codex and Google Gemini. The plugin distribution adds quality-of-life conveniences in the Claude ecosystem, but the standalone boomi-agentstudio, boomi-bdi, boomi-integration, boomi-marketplace, and boomi-datahub skills are portable to any agent that supports the standard.
Capabilities and scope
Can Boomi Companion modify components that were built in the UI?
Yes. You can reference any existing component from the platform using its component ID or URL, and Boomi Companion will pull the component along with its dependencies into your project folder. From there, you can ask Boomi Companion to modify, extend, or analyze it.
Does Boomi Companion support EDI and B2B trading partners?
Yes. EDI and B2B are in scope for the boomi-integration skill. Boomi Companion can create trading partner components, EDI profiles, and processes.
Can Boomi Companion build APIs and web service listeners?
Yes. Boomi Companion can convert existing processes into API endpoints using the Web Services Server (WSS) pattern, or build new listener-based processes from scratch. It handles the wrapper/subprocess pattern, operation configuration, and deployment.
Can Boomi Companion help me debug a failing process?
Yes. If you have configured an environment and runtime, Boomi Companion can query execution records, download execution logs, analyze errors, and suggest fixes. You can also point it at a failing process and ask it to troubleshoot; it will pull the process, review the logic, check for known error patterns, and propose changes.
Security
How should I handle Boomi integrations' connection credentials?
Configure the connection credentials directly in the Boomi Platform UI, then let Boomi Companion reference those connections by ID. This way, Boomi Companion does not need visibility into the credentials themselves, which keeps sensitive values, such as passwords, API keys, and OAuth tokens, out of your local workspace entirely.
To make this workflow easy, your template workspace includes a preferred_connections.md file where you can list the existing connections you want Boomi Companion to reuse. During a build, Boomi Companion checks this file first and pulls the referenced connections from the platform instead of creating new ones.
How are credentials handled?
Boomi designs this skill so AI agents do not have direct access to plaintext credentials in the context window. However, you may wish to take additional safeguards. For more information, refer to Developing Boomi Companion: Considering security for an AI agent skill.
What credentials does Boomi Companion need?
Boomi Companion requires your Boomi Platform username, a Platform API token, and your account ID. Optionally, you can configure an environment ID and runtime ID for deployment and testing.
Does my data leave my machine?
Yes. Boomi Companion is a skill for use by AI agents, and it exchanges data with your AI provider as part of its normal operation.
What data is sent to the AI provider, and is any of it retained or used to train models?
What gets sent depends on what you ask for. In a typical build session, the agent sends component metadata and the XML it is constructing. If you ask Boomi Companion to troubleshoot, execution logs may also be sent so the agent can interpret them. Anything you paste into the conversation, such as sample payloads, specifications, or requirements documents, is sent as well.
Your Platform API credentials stay in your workspace. The CLI tools make the API call, and the agent sees the result, not the token. Connection credentials configured in the Boomi platform remain in the platform; when Boomi Companion pulls a connector component, credential fields arrive as encrypted strings.
Boomi is not in this data path. Boomi Companion is open-source tooling that runs on your machine and talks to your AI provider under your agreement with that provider. Whether prompts and generated content are retained or used for training is governed by your contract with Anthropic, OpenAI, or whichever vendor you use. Most enterprise agreements exclude customer content from training, but that commitment comes from the model vendor, not from Boomi. Direct these questions to your AI provider's terms.
Boomi Companion itself adds no logging or telemetry by default. You can enable optional local-only debug logging with BOOMI_COMPANION_LOG_ACTIVITY=1; those logs stay on your machine and Boomi never collects them.
Should I use dedicated Boomi account or service account for Boomi Companion?
The account structure is a decision for your organization. Boomi Companion is designed to build, deploy, and test against a development or test environment. Assign it a role scoped to your lower environments, and promote to production through your organization's normal release process once you have reviewed the result. A role-based restriction is stronger than a convention: Boomi Companion cannot act on an environment its role does not reach, so a scoped role holds even if someone asks it to deploy to production in the middle of a session.
Treat its platform access the way you would treat a CI/CD pipeline's access: grant only the roles needed for the work you want it to do, and no more.
Both account patterns are in use. Some teams provision a single dedicated account for Boomi Companion. Others have each developer use their own account with an appropriately scoped role, which preserves individual attribution in the platform audit trail. A shared account is simpler to manage but attributes every action to one identity, which some security teams object to.
For a fuller discussion of scoping access, refer to Boomi Companion access boundaries.
Cost
Does Boomi Companion have a separate cost?
No. The Boomi Companion plugin and its skills are free. The only cost is your AI agent usage and your Boomi Platform consumption. There are no surcharges for using the Platform API that Boomi Companion uses.
Collaboration and customization
Can I customize Boomi Companion's behavior for my team?
Yes. Your template workspace includes a CLAUDE.md file where you can add custom instructions, preferences, and conventions. These persist across plugin updates and are copied into every new project you initialize. For example, you can specify naming conventions, preferred connector patterns, default error handling approaches, or any other team-specific standards.
Is Boomi Companion open source?
Yes. Boomi publishes Boomi Companion on GitHub under the BSD-2-Clause license, so you can read the source, fork it, and modify it for your own use. As a matter of project policy, Boomi curates the official distribution and does not currently accept pull requests against the canonical repository. Bugs and feature ideas are welcome through the project's intake channel, where the Boomi team evaluates them for inclusion in future releases.
Troubleshooting
What do I do if Boomi Companion keeps trying to do something in the GUI?
Some operations genuinely require the GUI: OAuth authorization flows, branded connector metadata import (such as Salesforce or NetSuite), and certain discovery-based configurations. When Boomi Companion tells you something needs to be done in the GUI, it is flagging a real platform limitation. Complete the step in the UI, then return to Boomi Companion to continue building.
My process deployed but is not working. How do I debug it?
Ask Boomi Companion to check the execution logs. It can query recent executions, download logs, and analyze what went wrong. Common issues include subprocess changes not picked up by the parent (redeploy the parent), environment variable references in XML (Boomi does not support ${ENV_VAR} syntax in component XML), and Message shape quote escaping in JSON payloads. Boomi Companion knows these patterns and will check for them.
Boomi Companion made a mistake. How do I undo what it built?
Everything Boomi Companion creates is a standard Boomi component on the platform. You can delete or modify any component through the Boomi UI just as you would with anything built manually. Locally, your project folder contains the XML files Boomi Companion generated; you can ask Boomi Companion to revert a change, or delete the local files and re-pull from the platform if needed. Nothing Boomi Companion does is irreversible.
What should I check if the connection test fails with curl exit code 56?
Exit code 56 before any HTTP response usually means a VPN or SSL-inspection tool (Zscaler, Netskope, Cisco Umbrella, or similar) is intercepting the connection between your machine and the Boomi platform. It is not a credential or .env problem.
The fix is to trust your organization's inspection certificate on the local machine. This is a one-time setup, and your IT or security team may already have documented steps for it.
On macOS, you can export the certificate from Keychain and make Node aware of it:
mkdir -p ~/.certs
security find-certificate -a -c "Zscaler" -p /Library/Keychains/System.keychain > ~/.certs/zscaler_root.pem
echo 'export NODE_EXTRA_CA_CERTS="$HOME/.certs/zscaler_root.pem"' >> ~/.zshrc
source ~/.zshrc
Replace Zscaler with the name of your organization's inspection product if it differs.
If your AI agent cannot respond to a simple "hello world" prompt either, the certificate is blocking the agent itself, not just Boomi Companion. If the agent responds normally and only the Boomi connection test fails, the certificate is likely trusted for the agent but not for the tooling Boomi Companion calls.
Certificate interception can also surface when installing or updating the plugin, as a server certificate verification failed error while cloning the repository. The same fix applies.
Why does Boomi Companion work in Claude Code but the connection test fails in Claude Cowork?
Cowork runs its commands in Claude's cloud sandbox rather than on your local machine, so your VPN or proxy is not in the path, and certificate fixes do not apply. Sandbox traffic routes through an egress gateway that resets connections to domains outside the Claude organization's allowed list, which produces a consistent exit code 56 before any HTTP response.
A Claude organization administrator can resolve this by adding *.boomi.com to the network allowlist.
Tips and tricks
How do I get the best results?
Give Boomi Companion enough context to work with. Consider whether you would have enough information to complete the task yourself if someone handed you the same prompt. Provide environment and runtime credentials in your .env file so it can test its own work. If it starts going in the wrong direction, interrupt and redirect rather than letting it continue.
Should I use Plan mode?
For complex builds, yes. Entering Plan mode (Shift+Tab twice) lets Boomi Companion think through its approach before building. This is especially useful for multi-component processes or unfamiliar use cases.
Do not clear context after Boomi Companion makes a plan; let it carry that thinking into execution.
How should I organize my work?
Create a separate project folder for each work effort and initialize it with /freshies. This keeps your template workspace reusable and your projects isolated from each other. You can customize your template workspace with personal instructions and preferences that persist across plugin updates.
Can I run multiple Boomi Companion sessions at once?
Yes. Tools such as tmux let you run multiple terminal sessions in parallel. Boomi Companion also works with Claude Code on the web, the desktop app, and claude.ai.
What if Boomi Companion does something unexpected?
Ask it to explain why it made the decision it did. Use that feedback to improve the instructions in your personal template workspace's CLAUDE.md file.
Prompt engineering
How specific should my prompts be?
Be specific about what you want to build, but let Boomi Companion decide how to build it. For example, "Build a REST API that accepts a JSON payload with customer name and email, validates the fields, and posts to Salesforce" is much more effective than "Build a Salesforce integration." Include the details you would give to a colleague, such as endpoints, field names, and expected behavior. You do not need to dictate which Boomi shapes to use.
Should I give one big prompt or break it into steps?
For simple processes, a single detailed prompt works well. For complex, multi-component builds, consider breaking the work into phases: design first, then build, then test. You can start with "Design a process that does X; do not build it yet, just tell me your plan" and then refine before telling it to proceed.
How do I correct course without starting over?
Be direct. If Boomi Companion is heading in the wrong direction, interrupt it and say what you want changed. For example: "Stop, do not use a Message shape there, use a Map instead." You do not need to re-explain the whole task, just the specific correction. Boomi Companion retains the full conversation context and can adjust.
What if I am not sure how to describe what I want in Boomi terms?
Describe the business outcome instead: "I need to pick up files from an SFTP server every 15 minutes, convert them from CSV to JSON, and send them to a REST endpoint." Boomi Companion has the platform knowledge to translate business requirements into Boomi components.
Can I ask Boomi Companion to explain its choices?
Yes, and you should. Asking "Why did you use a Branch shape here instead of a Route?" or "Walk me through how this process handles errors" helps you learn and catch design decisions you may want to change before deploying.
How do I handle long or complex conversations?
Claude works best with focused context. If you are switching to a completely different task, consider clearing the context (/clear) and starting fresh rather than carrying a stale conversation history. If you are iterating on the same process — building, testing, and fixing — keep the context intact so Boomi Companion can reference prior decisions and test results.
Are there prompts I should avoid?
Avoid vague, open-ended prompts such as "Build me something cool" or "Make an integration." Also avoid over-specifying implementation details that conflict with Boomi's best practices. For example, dictating exact XML structures when Boomi Companion already knows the correct component schemas.
Can I give Boomi Companion reference material to work from?
Yes. You can paste API documentation, sample payloads, schema definitions, or requirements documents directly into the conversation. You can also place reference files in your project workspace; Boomi Companion can read and use them during the build. The more concrete your inputs (actual field names, real sample data, actual endpoint URLs), the better the output.
Support
Is Boomi Companion an officially supported Boomi product?
Boomi Companion is a publicly available developer offering, not an officially supported Boomi product. It is provided as-is and is not covered by Boomi support agreements or SLAs. Boomi curates and maintains this offering on a best-effort basis. Treat it as a self-service resource. Boomi reserves the right to modify or discontinue it at any time without notice.
