Install your Agentic Kit on HubSpot CMS

HubSpot CMS doesn't expose a filesystem you can write to directly, but it ships two cleanly-supported paths for serving arbitrary files at your root domain: the File Manager (host the file, redirect the canonical URL), and HubL custom templates (render the content from a HubL template at a fixed slug).

The File Manager + URL Redirects path is the most reliable across plans, including Starter. This guide covers that approach.

You'll be done in under 8 minutes.

Step 1 — Upload the three files to File Manager

In HubSpot, go to Marketing → Files and Templates → Files.
Click Upload files and add the three files from your kit ZIP:
- agents.json
- llms.txt
- agent-instructions.md
After each upload, click the file row and click Copy URL. The public URLs look like: https://yourdomain.hubspotusercontent-na1.net/hubfs/agents.json
Save all three URLs in a notepad — you need them in Step 2.

⚠️ If HubSpot rejects the file types File Manager occasionally restricts uploads by file extension. The workaround: rename with a .txt suffix (agents.json.txt), upload, and use that as the redirect target. Agents follow the redirect regardless of filename suffix.

Step 2 — Add URL redirects

In HubSpot, go to Settings → Website → Domains & URLs → URL Redirects.
Click Add URL redirect three times and create:

Original URL	Redirected URL	Type
`/agents.json`	the File Manager URL for `agents.json`	301
`/llms.txt`	the File Manager URL for `llms.txt`	301
`/agent-instructions.md`	the File Manager URL for `agent-instructions.md`	301

Save each.

Step 3 — Verify

Open each URL in a new tab on your live HubSpot domain:

https://yourdomain.com/agents.json
https://yourdomain.com/llms.txt
https://yourdomain.com/agent-instructions.md

Each should serve the file content via a 301 redirect to the hubspotusercontent URL. Agents follow 301s without issue.

Step 4 (recommended) — Add the auto-discovery snippet

Tell AI bots where to find these files directly from your <head>.

In HubSpot, go to Settings → Website → Pages.
Scroll to Site header HTML under the Templates section.
Paste:

<link rel="alternate" type="application/json" title="Agent Action Map" href="/agents.json">
<link rel="alternate" type="text/plain" title="LLM Context" href="/llms.txt">
<link rel="alternate" type="text/markdown" title="Agent Runbook" href="/agent-instructions.md">

Click Save. The change applies to all pages using the default template.

Alternative: HubL custom templates (advanced)

If you're on CMS Hub Professional or Enterprise and want true root-served files (no redirect), you can create a HubL template per file:

Go to Marketing → Files and Templates → Design Manager.
Click File → New file → HTML & HUBL.
Set the template type to None (so it serves raw content).
Paste the literal file content (no surrounding HTML).
Publish at the desired URL slug — e.g. /agents.json.

You'll need to set the response content-type via a {# headers content_type="application/json" #} HubL directive at the top of the template. Check HubSpot's current HubL docs for the exact syntax — it has shifted between CMS Hub generations.

For most installs the File Manager + Redirects flow is faster, more plan-compatible, and easier to update when you regenerate the kit.

Troubleshooting

Redirect doesn't apply to the root domain. HubSpot redirects are scoped per primary domain. If you serve multiple domains, add a redirect for each.

File Manager URL changes after re-upload. Re-uploading a file mints a new URL. If you regenerate the kit and re-upload, update the three redirects to point at the new URLs.

File downloads instead of displaying inline. HubSpot serves some extensions with Content-Disposition: attachment. This is harmless for AI agents — they read the bytes either way.

HubSpot adds tracking parameters to the redirect URL. HubSpot sometimes appends _hsmi or __hssc query parameters to redirected URLs. Agents ignore these; the canonical /agents.json remains the resolvable URL.