Skip to content
Talk to an engineer

Get started

Setup

SDK initialization flow: load script, identify user, show agent 1 Load SDK <script> snippet async, non-blocking 2 Identify user foldspace.identify() ties session to user 3 Show agent .agent(key).show() widget appears inside foldspace('when', 'ready', ...)

Install the Foldspace SDK with one snippet. Copy yours from Agent Studio → Setup (pre-filled with your product key and Agent Key) and paste it before the closing </body> tag. The SDK loads asynchronously, so it never blocks or slows your site.

index.html
<body>
<!-- Your HTML content goes here -->
<script type="text/javascript">
(function (w, d, u, n, k, c) {
w[n] = w[n] || function () { (w[n].q = w[n].q || []).push(arguments); };
w.__FOLD_SPACE__ = n; w[n].k = k; w[n].c = c;
var s = d.createElement('script'); s.async = true; s.src = u + '?k=' + k;
var h = d.getElementsByTagName('script')[0]; h.parentNode.insertBefore(s, h);
})(window, document, 'https://script.eucerahive.io/web/sdk/foldspace.js', 'foldspace', 'YOUR-PRODUCT-KEY');
// Identify the signed-in user so the agent has real context and conversation
// history persists for this user across sessions and devices.
const context = {
user: { id: 'YOUR-USER-ID' },
subscription: { id: 'YOUR-SUBSCRIPTION-ID' },
};
foldspace('when', 'ready', () => {
foldspace.identify(context);
// Render the agent — choose embedded or the floating widget below.
});
</script>
</body>

Replace YOUR-PRODUCT-KEY with your product key, the EU-… value in the snippet under Agent Studio → Setup → Installation. It identifies your product, not the agent. Wherever you call foldspace.agent(), pass the Agent Key field from the same page instead: the agent’s API name, for example support-agent.

If the agent doesn’t appear after adding the snippet, check your Content Security Policy first. A CSP that doesn’t allow script.eucerahive.io blocks the SDK silently, and the browser console names the directive it violated.

foldspace.identify() ties the session to your signed-in user. This is what gives the agent real user context and persists each user’s conversation history across sessions and devices, instead of treating every visit as a new anonymous session.

Identity is built in, so the agent runs without identify(), but pass your real user.id (and subscription.id, if you bill by subscription) in production. Add fields like email, name, role, or your own attributes to enrich context and analytics. See User context for the full field list and custom attributes.

Show the agent: embedded or floating widget

Section titled “Show the agent: embedded or floating widget”

This is the first thing everyone asks, so decide it as part of setup. The agent renders two ways — pick one inside the same when('ready') callback:

Floating widget vs embedded mode comparison Floating (default) Embedded mode container
  • Embedded (recommended). The agent mounts inline inside a container you place in your layout, so it feels like a native part of your product. This is the way we recommend shipping — it drives the most engagement. See Embedded mode.
  • Floating widget. The agent rides in a floating launcher that overlays your app. Quickest to drop in when you don’t yet have a place to host it inline.

Mount the agent into a container element you control:

// A container somewhere in your layout.
const agentContainer = document.getElementById('agentContainer');
foldspace('when', 'ready', () => {
foldspace.identify(context);
foldspace.agent({
apiName: 'YOUR-AGENT-KEY', // Agent Key from Agent Studio → Setup
mode: 'EMBEDDED',
configuration: {
embeddedConfiguration: { container: agentContainer },
},
});
});

See Embedded mode for layout and sizing options.

To keep the agent off for some of your tenants, such as schools that haven’t approved Foldspace, render the snippet only into pages for approved tenants. The snippet is what creates the <script> tag that loads foldspace.js from script.eucerahive.io. Where the snippet doesn’t run, the SDK never loads: the page makes no request to Foldspace and sends it no data.

Make the check on your server, so pages for other tenants never contain the snippet. The snippet goes inside the condition unchanged:

render-page.js
// Runs on your server. `tenant.foldspaceEnabled` is your own per-tenant setting.
function foldspaceSnippet(tenant) {
if (!tenant.foldspaceEnabled) {
return '';
}
return `
<script type="text/javascript">
(function (w, d, u, n, k, c) {
w[n] = w[n] || function () { (w[n].q = w[n].q || []).push(arguments); };
w.__FOLD_SPACE__ = n; w[n].k = k; w[n].c = c;
var s = d.createElement('script'); s.async = true; s.src = u + '?k=' + k;
var h = d.getElementsByTagName('script')[0]; h.parentNode.insertBefore(s, h);
})(window, document, 'https://script.eucerahive.io/web/sdk/foldspace.js', 'foldspace', 'YOUR-PRODUCT-KEY');
// Identify the signed-in user so the agent has real context and conversation
// history persists for this user across sessions and devices.
const context = {
user: { id: 'YOUR-USER-ID' },
subscription: { id: 'YOUR-SUBSCRIPTION-ID' },
};
foldspace('when', 'ready', () => {
foldspace.identify(context);
// Render the agent — choose embedded or the floating widget below.
});
</script>`;
}

Write the same condition in whatever renders your pages (a template, a layout component, a server route) and output the result before the closing </body> tag.

Guard every other foldspace(...) call in your frontend the same way. On pages without the snippet, window.foldspace is undefined, so an unguarded foldspace(...) call throws a ReferenceError:

help-button.js
if (window.foldspace) {
foldspace('when', 'ready', () => {
foldspace.agent('YOUR-AGENT-KEY').show();
});
}

Set the agent’s appearance, greeting, and behavior in Agent Studio → Style & Behavior, or override it in code from the SDK configuration reference.

Add the Foldspace MCP server to your editor, and your assistant can browse your actions and implement them in your code. See Vibe coding.