Chapter 1: Setting Up The Project

In this chapter, you will clone the guide repository, configure local environment files, start the ACME Banking sample apps, and inspect the starting workspace.

At this point ACME Banking does not have an assistant yet. The starting project gives you the application landscape that the assistant will join in later chapters.

The starter project contains empty shells for several io.Intelligence libraries you will configure later:

Clone The Guide Repository

Clone the public guide repository:

git clone https://github.com/InteropIO/iointel-guides.git
cd iointel-guides

The repository contains the starter project, the solution project, and the local backend:

iointel-guides/
  io-assist-anywhere-start/
  io-assist-anywhere-solution/
  agentic-backend/

Use io-assist-anywhere-start while following the guide. The io-assist-anywhere-solution directory contains the completed reference implementation.

Understand The Starter Frontend

Open the starter frontend package:

cd io-assist-anywhere-start

This package contains a small Lerna-managed frontend workspace and a prepared MCP HTTP server shell.

The Lerna workspace has seven apps:

App	Port	Purpose
`apps/io-cb-home`	`4200`	The io.Connect Browser platform that hosts the ACME Banking workspace
`apps/client-list`	`4201`	A simple app that displays the bank's current clients
`apps/client-portfolio`	`4202`	A simple app that displays portfolio details for the selected client
`apps/io-cd-mcp-host`	`4203`	A shell service app reserved for the io.Connect Desktop MCP host implementation
`apps/io-assist-angular`	`4003`	A default Angular CLI app shell reserved for an Angular io.Assist implementation
`apps/io-assist-react`	`4004`	A default Vite React app shell reserved for a React io.Assist implementation
`apps/io-assist-custom`	`4005`	A scaffolded custom assistant shell reserved for the AI Web implementation

The two assistant app shells are intentionally unmodified framework starter apps at this stage. They are available so later assistant chapters can begin from a known Angular or React baseline without adding framework scaffolding to the guide steps.

The io-cd-mcp-host app is also only a shell at this stage. It connects to io.Connect Desktop and loads the Workspaces API, but it doesn't contain MCP Web or io.Intelligence logic yet. You will add that in Chapter 9.

The io-assist-custom app starts as a small chat UI scaffold. It includes the basic Vite setup, styling, and chat view helpers, but it doesn't contain AI Web logic yet. You will add that in Chapter 11.

The package also includes a separate Node.js shell project:

mcp-http-server/

This project isn't part of the Lerna frontend apps and it doesn't run when you execute npm start. It is prepared for the io.Connect Desktop chapter where you will build a dedicated MCP HTTP server. The shell already contains the TypeScript, Rollup, and environment-file setup needed to produce a dist/index.cjs bundle that io.Connect Desktop can start as a Node service app.

The platform app owns the io.Connect Browser configuration in:

apps/io-cb-home/src/config.json

That file registers the two banking apps and defines a workspace layout named client-management.

apps/io-cb-home/src/config.json
{
  "apps": [
    {
      "name": "client-list",
      "type": "window",
      "details": {
        "url": "http://localhost:4201"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    },
    {
      "name": "client-portfolio",
      "type": "window",
      "details": {
        "url": "http://localhost:4202"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    }
  ]
}

The real file also includes the saved client-management workspace layout that opens both banking applications side by side. The assistant app shells are not loaded into this workspace yet.

Understand The Platform Plugin

The starter platform includes a guide plugin that registers an interop method named getClients.

apps/io-cb-home/src/app/plugin.ts
await io.interop.register("getClients", () => ({
  clients
}));

The client list app uses this method instead of owning the client collection itself. This keeps shared guide data in the platform and gives later assistant work a stable platform capability to build on.

The returned value has this shape:

{
  clients: Client[];
}

Understand The Agentic Backend

The backend lives at the repository root:

agentic-backend/

It is a standalone Mastra application. It has its own package.json, dependencies, .env-template, and source files under:

agentic-backend/src/mastra/

The backend starts with a minimal io-agent:

agentic-backend/src/mastra/agents/io-agent.ts
export const ioAgent = new Agent({
  id: "io-agent",
  name: "IO Agent",
  instructions: "",
  model: anthropic("claude-opus-4-5")
});

You will expand this backend in later chapters when the assistant is ready to connect to an agent.

Create The Frontend Environment File

From io-assist-anywhere-start, copy the frontend template:

cp .env-template .env

Open .env and add your license keys:

io-assist-anywhere-start/.env
VITE_IO_INTELLIGENCE_LICENSE_KEY="your-io-intelligence-license-key"
VITE_LICENSE_KEY="your-io-connect-browser-license-key"

The platform app has a script that reads the root frontend .env file and creates the local platform .env file it needs.

warning

Do not commit .env files. Keep real license keys local to your machine.

Create The Backend Environment File

Move to the backend package and copy its template:

cd ../agentic-backend
cp .env-template .env

Add your Anthropic API key:

agentic-backend/.env
ANTHROPIC_API_KEY="your-anthropic-api-key"

You do not need to start the backend to inspect the initial workspace, but setting it up now avoids interruption when the assistant chapters begin.

Install Dependencies

Install the frontend dependencies:

cd ../io-assist-anywhere-start
npm install

Install the backend dependencies:

cd ../agentic-backend
npm install

Run The Starting Frontend

Start the frontend package from io-assist-anywhere-start:

cd ../io-assist-anywhere-start
npm start

This starts all five Lerna frontend apps:

App	URL
io.Connect Browser platform	`http://localhost:4200`
Client List	`http://localhost:4201`
Client Portfolio	`http://localhost:4202`
io.Assist Angular shell	`http://localhost:4003`
io.Assist React shell	`http://localhost:4004`

For guide validation, open the platform URL:

http://localhost:4200

Do not open the client apps directly when you want to validate io.Connect behavior. The client apps need to run inside the platform workspace for workspace context and platform interop to behave like the guide expects. The Angular and React assistant URLs are useful for checking that the framework shells start, but they do not participate in the workspace yet.

Open The Client Management Workspace

In the browser:

Open http://localhost:4200.
Select the logo in the top-left corner to open the Launchpad.
Select the client-management workspace.

The workspace should open with:

client-list on one side
client-portfolio on the other side

Open the browser console and look for these messages:

IO Connect Browser Platform initialized
Client List App Started
Client Portfolio App Started

You may also see:

Guide plugin started

Verify The Starting Behavior

The Client List app should show a short list of ACME Banking clients. Selecting a client should visually select that row and write the selected client to the workspace context.

The Client Portfolio app should react to the workspace context and display the selected client's portfolio.

You can also inspect the platform interop method from the top window console:

const result = await window.io.interop.invoke("getClients");
console.log(result.returned.clients);

The result should be an object with a clients array:

{
  clients: [
    {
      id: "CL-10024",
      portfolioId: "PF-8801",
      firstName: "Amelia",
      lastName: "Reed"
    }
  ]
}

The actual array contains several clients. The snippet above shows only one item so the shape is easy to see.

Run The Backend

When you are ready to check the backend, start it in a separate terminal:

cd ../agentic-backend
npm start

Mastra starts a local development server. Later chapters will connect io.Assist to this backend.

What You Have Now

You now have:

a running io.Connect Browser platform
a saved ACME Banking workspace
two simple banking apps loaded in that workspace
default Angular and React assistant app shells for later chapters
a prepared MCP HTTP server shell for the io.Connect Desktop MCP HTTP chapter
a platform-owned getClients interop method
a root-level agentic backend ready for later chapters

In Chapter 2: MCP Web Integration in io.Connect Browser, you will expose the platform-owned getClients method through MCP Web.

Related API References​

Clone The Guide Repository​

Understand The Starter Frontend​

Understand The Platform Plugin​

Understand The Agentic Backend​

Create The Frontend Environment File​

Create The Backend Environment File​

Install Dependencies​

Run The Starting Frontend​

Open The Client Management Workspace​

Verify The Starting Behavior​

Run The Backend​

What You Have Now​

Related API References