<style> .chartjs-size-monitor { display: none !important; height: 0 !important; overflow: hidden !important; }p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><p><strong>In this guide we will cover:</strong></p><p><strong>- What Claude Code is & Our Disclaimer</strong></p><p><strong>- Risks</strong></p><p><strong>- Best Practices</strong></p><p><br></p><p data-pasted="true">The purpose of this article is to document the risks of integrating Claude Code with Halo, and Halo's recommended practices for mitigating them. Please note that this is <strong>not </strong>a guide on how to set up a Claude Code integration with Halo. </p><p><br></p><p>This guide is written specifically for Halo administrators, partners, or consultants that are evaluating, or actively maintaining, a Claude Code integration with Halo. It assumes familiarity working with Halo's API, as well as familiarity with the concept of Claude Code itself.</p><p><br></p><p>In addition to Halo's own, it is advisable to also explore Anthropic's best practices: <a href="https://code.claude.com/docs/en/best-practices" target="_blank" rel="noopener noreferrer">Best practices for Claude Code</a>. </p><hr><p><br></p><p><strong><span style="font-size: 14pt;">What Claude Code is & Our Disclaimer</span></strong></p><p>Claude Code is Anthropic's agentic coding tool. It reads a codebase, edits files, runs commands, and integrates with other tools in a technology stack. </p><p>In a Halo context, Claude Code operates as an agent with the same reach as a terminal session - this is the source of both its value and its risk.</p><p><br></p><p>The aim of this documentation is to outline the risks of integrating Claude Code with Halo, and to provide best practices to those who aim to do so, in an attempt to mitigate said risks. </p><p><br></p><p><strong>Important:</strong> In the event that you choose to integrate Claude Code with Halo, although we will always endeavour to help our customers however we can, please do be aware that Halo is not responsible for any changes made by Claude Code to your instance. The practices in this guide reduce risk; they do not eliminate it.</p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">Risks</span></strong></p><p><span style="font-size: 11pt;">This section outlines some main identified risks, and advisable methods of mitigation, for integrating Claude Code with Halo. You will find a quick reference risk/mitigation table, followed by expanded section below. </span></p><p><br></p><p><span style="font-size: 12pt;"><strong>Quick Reference Table</strong></span></p><p><br></p><table class="styled-table grid" style="width: 100%; height: 400px;"><colgroup><col style="width: 47.7888%;"></colgroup> <colgroup><col style="width: 52.2112%;"></colgroup><tbody><tr><td style="text-align: center; background-color: rgb(0, 204, 248);"><strong><span style="color: rgb(255, 255, 255); font-size: 14pt;">Risk</span></strong></td><td style="text-align: center; background-color: rgb(0, 204, 248);"><div style="text-align: center;"><strong><span style="color: rgb(255, 255, 255); font-size: 14pt;">Primary Mitigation</span></strong></div></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">Unrestricted file and web access enables prompt injection and data exfiltration.</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Run Claude Code in a Docker container or VM.</span></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">Autonomous action without review ("auto mode").</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Disable auto mode & require instructor approval before execution.</span></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">Overzealous changes beyond the scope of a given instruction.</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Define explicit boundaries in context files & use plan mode.</span></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">API access bypasses UI validation, risking breakage of dependent entities.</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Test in a non-production environment before deploying changes.</span></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">Credentials stored in plaintext are exposed to prompt injection.</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Use a secret manager or externally scoped environment variables.</span></td></tr><tr><td style="text-align: left;"><span style="font-size: 12pt;">Untracked identity obscures which changes originated from Claude Code.</span></td><td style="text-align: left;"><span style="font-size: 12pt;">Authenticate Claude Code as a dedicated Agent.</span></td></tr></tbody></table><p><br></p><p><strong><span style="font-size: 12pt;">File Access & Prompt Injection</span></strong></p><p>Claude Code executes in the terminal with the same privileges as the user account that runs it. Meaning it can read, modify, and execute anything that account's permissions allow, including files, scripts, and copying data to external destinations. This is the source of its capability, and the reason access controls and environment isolation are essential. Because it also has web access, it can encounter malicious pages containing injected instructions - text designed to redirect an AI agent's behavior, such as exfiltrating local files. Claude Code cannot reliably distinguish the origin of instructions it receives, which makes this class of attack effective regardless of the model's quality. </p><p><br></p><p>The most effective mitigation for this is to run Claude Code inside a Docker container or, at minimum, a Virtual Machine (VM). This isolates it from the rest of the system, and limits what data it can reach. See the best practices section for more information.</p><p><br></p><p><strong><span style="font-size: 12pt;">Autonomous Behaviour</span></strong></p><p data-pasted="true">It is possible to put Claude Code into auto mode, acting on instructions without waiting for approval of the payloads or scripts it will run. </p><p>Independent of auto mode, Claude Code may also act beyond the scope of an instruction - applying changes it judges beneficial even when they were not requested.</p><p><br></p><p>The best mitigation for this is to use an approval-required permission mode, avoid connecting to production environments, review payloads and scripts before they run, require a danger assessment for each change, and encode boundaries directly into context files. For more information, see the best practices section of this article.</p><p><br></p><p data-pasted="true"><strong><span style="font-size: 12pt;">API Validation & Platform Complexity</span></strong></p><p>The Halo UI enforces guardrails that protect the integrity of linked configurations - for example, preventing deletion of a workflow currently in use. These guardrails are not fully enforced at the API layer - this is not unique to Halo, it is an inherent characteristic of API access across most platforms, but it is important to be aware of given that Claude Code acts through the API exclusively.</p><p>Combined with Halo's configuration complexity and Claude Code's limited domain-specific knowledge of Halo, this makes certain mistakes difficult to anticipate, difficult to diagnose, and in some cases irreversible without a rollback. </p><p><br></p><p>To mitigate this risk, providing strong context, working in non-production environments, and maintaining backups before making changes are all strongly recommended practices.</p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">Best Practices</span></strong></p><p><strong><span style="font-size: 12pt;">Secure & Controlled Authentication</span></strong></p><p>Claude Code supports any authentication method available when creating a Halo API application. (Figure 1). </p><p>It is, however, strongly advised that you Authenticate Claude Code as a dedicated Agent - a Halo identity used to authenticate an API application - rather than under a shared credential or another Agent working elsewhere in the system. This enables full auditing of configuration changes and ensures issues are traceable to Claude Code, rather than discovered only after damage occurs. Use an API-only Agent if you wish to avoid consuming a named license. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhjZTE4M2M5LTcwOTEtNDBkMi1iOWU3LTVlMWFiZTRlNmRlNCJ9.BPHDYVvMf12WQmhL7uYDr2l-3ObicJ3j3RK3dZmT5U8" class="fr-fic fr-fil fr-dib" width="797" style="width: 799px; height: 533.6px;" height="534"></p><p><strong><span style="font-size: 10pt;">Fig 1. The authentication methods available for an API application</span></strong></p><p><br></p><p>Grant the API application least-privilege access: it should only have access to the data and configuration areas Claude Code needs for its assigned tasks. Inflated permissions increase the volume and sensitivity of data exposed if Claude Code is prompt injected or misconfigured.</p><p><br></p><p>For information on creating API applications and setting the permissions/scopes, please visit this guide: <a href="https://usehalo.com/halopsa/guides/1823/" target="_blank" rel="noopener noreferrer">Creating API Applications</a>.</p><p>For information on restricting configuration access for roles, please visit this guide: <a href="https://usehalo.com/haloitsm/guides/2682" target="_blank" rel="noopener noreferrer">Agent Team, Department and Roles Restrictions</a>.</p><p><br></p><p><strong><em>Important: Although it is very common, storing the access credentials for the Halo environment(s) as plaintext JSON files, .env files, or hardcoded values inside of Claude Code's file structure should be avoided. Storing the credentials in this way exposes the Halo environment(s), and the data stored within, to the risk of access by Claude Code during normal operations and amplifies the risks associated with prompt injection. <strong data-pasted="true"><em>Hardcoded credentials are especially high risk, as they become permanently embedded in Claude's version control history.</em></strong> Where possible, for credential storage, employ more secure methods such as a secret manager or shell-level environment variables set outside the project directory. If an environment (.env) file is required, then it is advisable to use an encrypted .env file and only decrypt it at runtime. </em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Isolate The Environment</span></strong></p><p>Run Claude Code inside a Docker container or virtual machine (VM), not on a local machine with unrestricted access to its own data. This practice allows for full control of your files and the information that Claude Code can access. </p><ul><li>Virtual Machine ("VM"): An isolated, software-based computer running inside your actual machine. It behaves like a standard computer but is isolated from the host system, giving you full control over file access and the data Claude Code can reach.</li><li>Docker Container: A lighter-weight solution that shares some host components but still isolates and controls data access.</li></ul><p>Isolation is the primary mitigation for prompt-injection risks. To learn more about Docker and Docker containers, we encourage you to visit Docker's website: <a href="https://www.docker.com/" target="_blank" rel="noopener noreferrer">Docker</a>.</p><p><br></p><p><strong><span style="font-size: 12pt;">Restriction To Non-Production Environments</span></strong></p><p>Connect Claude Code to a sandboxed Halo environment. Once changes are tested and approved, either promote them from the dev environment or export and import the config commit files into the target environment. For information on working with configuration change tracking or instance pipeline management, please do visit the guide on our website:<a href="https://usehalo.com/halopsa/guides/1888" target="_blank" rel="noopener noreferrer"> Configuration Change Tracking and Instance Pipeline Management</a>. </p><p><br></p><p>If Claude Code is connected to a production environment and makes untested changes to that environment, it risks irreversible damage that may require a full rollback of your environment. It also means production credentials are stored wherever Claude Code runs, increasing the impact of any prompt-injection incident.</p><p><br></p><p data-pasted="true"><strong><span style="font-size: 12pt;">Provide Context & Rules</span></strong></p><p>Any knowledge gap between the instructor and Claude Code will be filled by Claude - likely with incorrect or damaging assumptions. It is important to close this gap as much as possible by providing specific, written context. </p><p><br></p><p>Store context that should apply to every instruction in markdown (.md) files within Claude Code's project structure. To a certain extent, context will differ per instructor and environment, but below are some recommended context suggestions:</p><ul><li>What Halo is, your relationship to it, and why Claude Code has been integrated </li><li>Configuration modules in use and their dependent entities</li><li>Example payloads and scripts for common configurations, including expected responses and downstream effects</li><li>Interdependent or co-dependent configurations, and what breaks if one is changed or removed</li><li>What is prevented by the UI and why</li><li>Explicit rules dictating what Claude is and is not permitted to change - stricter rules will produce more predictable behaviour</li><li>The database schema - how to distinguish system tables from custom tables, how custom fields are placed and removed, and which tables are interdependent</li></ul><p>When providing examples of configurations and payloads, also provide expected responses and what the effect is on any related entities where possible, so that Claude can grasp the level of impact for that change. </p><p><br></p><p>There is no single correct file structure. A common practice, however, is the following: one <a href="https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md" target="_blank" rel="noopener noreferrer">general context .md file</a> that is injected automatically with every instruction to Claude, plus supplementary 'skills' that have additional context on particular areas of the system. Skills are on-demand context modules invoked with a slash command (/SKILLNAME). See Skills and MCP tools for more information on skills.</p><p><br></p><p>In addition to the context files and skills, instruct Claude Code to maintain its own knowledge base of .md articles and to update it at the end of each session with new or refined information. This compounds knowledge over time without ongoing effort on your part.</p><p><br></p><p>For more on context provisioning in Claude Code, see Anthropic's documentation: <a href="https://code.claude.com/docs/en/best-practices#provide-specific-context-in-your-prompts" target="_blank" rel="noopener noreferrer">Provide specific context in your prompts</a>.</p><p><br></p><p><strong><span style="font-size: 12pt;">Confirm The Target Environment</span></strong></p><p>Before starting a session, confirm which Halo environment Claude Code will act in - particularly if it holds credentials for more than one environment, or if you are a partner or consultant with access to multiple customer environments. Previously changes have been misdirected to the wrong environment on occasion when this step has been skipped.</p><p><br></p><p><strong><span style="font-size: 12pt;">Require A Pre-Change Danger Assessment</span></strong></p><p>For every instructed change, require Claude Code to evaluate the blast radius and severity of the change before acting. This surfaces high-impact changes for review and can prompt Claude Code to reconsider its own approach.</p><p><br></p><p><strong><span style="font-size: 12pt;">Maintain Backups (Checkpoints)</span></strong></p><p>Require Claude Code to take a backup of the current configuration before committing a change. </p><p><br></p><p>Backups of this nature, in the context of Claude Code, are commonly referred to as '<a href="https://code.claude.com/docs/en/best-practices#rewind-with-checkpoints" target="_blank" rel="noopener noreferrer">checkpoints</a>'. A checkpoint occurs when Claude takes a snapshot of all files before making a change, making it possible for Claude to roll back to this checkpoint if it becomes necessary.</p><p><br></p><p><strong><em>Note: Checkpoints persist across sessions.</em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Disable Auto Mode</span></strong></p><p>Do not use auto mode, regardless of how much context or training Claude Code has received. In auto mode, Claude Code posts payloads and scripts through the API without your review. </p><p>Anthropic recommends plan mode for integrations with external platforms: Claude Code researches and plans the change, presents the plan, and waits for direction before acting. Other approval-required modes do exist; none are foolproof, but they all substantially reduce the risk of unreviewed autonomous action.</p><p><br></p><p>See Anthropic's <a href="https://code.claude.com/docs/en/permission-modes" target="_blank" rel="noopener noreferrer">Permission Modes</a> for more information, particularly "<a href="https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode" target="_blank" rel="noopener noreferrer">Analyze before you edit with plan mode</a>".</p><p><br></p><p><strong><span style="font-size: 12pt;">Skills & MCP Tools</span></strong></p><p>Where the use case is covered, use the MCP endpoint rather than a direct API call. MCP requests are validated, so they behave more like UI-driven requests - for example, correctly triggering dependent entity creation. MCP tool coverage is currently narrow, but developing; it is recommended to adopt MCP tools as they become available for a given operation.</p><p><br></p><p>It is also advisable to keep in mind that you can create 'skills' in Claude Code - context modules invoked with /SKILLNAME - that extend its capabilities on demand rather than injecting context on every instruction. Use skills for project review, housekeeping checks, SQL operations, documentation work, or specific API call patterns. For information on how to create skills in Claude Code, see: <a href="https://code.claude.com/docs/en/skills" target="_blank" rel="noopener noreferrer">Extend Claude with skills</a>.</p><p><br></p><p><strong><em>Note: Halo's AI product team plans to publish 'official skills' to skills marketplaces by the end of the year.</em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Manage Session Hygiene </span></strong></p><p>Claude Code's context window fills quickly, and performance degrades as it fills - commonly once a session exceeds roughly 40–60% of available memory. Past that point, Claude Code may begin to lose earlier context, producing unexpected behavior and increasing the risk of unintended changes to the Halo environment.</p><p><br></p><p>For this reason it is important to keep sessions compact - give concise instructions, and start new sessions rather than extending long ones. For more information on how to do this effectively, see Anthropic's <a href="https://code.claude.com/docs/en/best-practices#manage-context-aggressively" target="_blank" rel="noopener noreferrer">Manage Context Aggressively</a>. </p><p><br></p><p><strong><span style="font-size: 12pt;">Maintain Existing Change Protocols</span></strong></p><p>Changes made by Claude Code should follow the same change control process as any other configuration change: a recorded request, a documented approval and approver, pre-change review, scheduling, and post-change verification. Do not treat Claude Code's changes as exempt from this process.</p><p>This reinforces the recommendation against connecting to production - changes should be made and reviewed in a dev environment before being promoted. For guidance on maintaining your change controls in Halo, see the <a href="https://usehalo.com/haloitsm/guides/1926" target="_blank" rel="noopener noreferrer">Change Management</a> and <a href="https://usehalo.com/haloitsm/guides/2396/" target="_blank" rel="noopener noreferrer">Approval Processes</a> guides on our website. </p><p><br></p><p><strong><span style="font-size: 12pt;">Data Usage</span></strong></p><p>How Claude Code handles data depends on your Anthropic package and model provider. Confirm your organisation's data-handling requirements are compatible with the package and provider you use: <a href="https://code.claude.com/docs/en/data-usage" target="_blank" rel="noopener noreferrer">data usage</a>.</p>
