Downloads & Setup

The home page of the admin console offers three downloads: Download Ext, Download Site and Download Toolkit. They are three different tools for three different people, and nothing else in the platform depends on them — an organization works without any of them installed. Each one is a plain file from a public GitHub repository, so you can also share the link directly.

Node.js 18 or newer

Runs the reference site and the toolkit's runner; npm comes with it. Get it from nodejs.org. Needed for Entanglement and Keen Mastering, not for the extension.

An unzip tool

Two of the downloads are zip archives. Windows Explorer and macOS Finder open them natively; on Linux use unzip or tar -xf. Each archive unpacks into one folder named after its repository — that folder is what you work in.

Visual Studio Code

The Shira Flow Builder is a VS Code extension — the canvas, the deploy panel and the debuggers all live inside VS Code.

Claude Code

The AI assistant the toolkit is written for — its slash commands are Claude Code commands, and it connects to the Keen MCP Server for you. Another assistant that can register an HTTP MCP server can use the MCP Server directly, but the packaged commands are Claude Code's.

ngrok (or another tunnel)

A site running on your own machine has no public address, yet the platform must reach it to deliver its change notices and the certificate. A tunnel gives it one. The toolkit is built around ngrok (ngrok.com); another tunnel with a public https address works for a hand-made setup. Not needed once the site runs on a real host.

Git

Optional. The downloads are plain archives, not clones — you own the copy and version it however you like.

MCP — the Model Context Protocol — is an open standard that lets an AI assistant discover and call tools a server offers, instead of guessing at screens or scripts. Claude Code, and a growing number of other assistants, speak it. KeenAgents runs an MCP server of its own, the Keen MCP Server, at https://<your-host>/mcp — the same host as your admin console. Its tools mirror the console: create a space, an agent, the API access chain, a contract, rebuild a cache, wake a partner site, provision the end-user identity a bot chats with.

An assistant signs in with an MCP account — a login for a program, not a person, that you create once under Organization → MCP Accounts: a name, a role and an Enabled switch, with an id and a secret shown once. From then on the assistant acts exactly as that account, limited by that role's permissions, and every action lands in the audit trail under it. Four things no role opens to it: your people's accounts, roles, other MCP accounts, and your consumers' records — an assistant can never widen its own access.

1. Download Ext on the console's home page saves the .vsix file.
2. Install it into VS Code — from a terminal or from the Extensions view.
3. Open the Shira Flow Builder view VS Code now shows and connect it to a space: your KeenAgents host, the space's id and its deployment token — both on the space's page in the console (Ai → Spaces), each with a copy button.
4. Build the flow on the canvas, then Connect → Upload: the platform checks and compiles the project and it is live in that space at once. Set a breakpoint and run a real conversation to step through it.

# from a terminal (VS Code's "code" command on your PATH)
code --install-extension shira-flow-builder-vs-0.0.2.vsix

# or inside VS Code: Extensions → the "…" menu → Install from VSIX…

The extension is the hand-driven way to build; the toolkit below is the same job done by an assistant. They can share a project folder — the extension edits the very files the assistant writes.

The site needs a tenant on the console side before it can talk to the platform. An admin creates, under Api: a Client (the site's server identity — its secret is shown once), a Certificate, a Consumer Contract that offers the space your agent lives in, a Webhook entry (the site's public Origin plus its notification URL), and an Api Key binding all four. That is the whole recipe of Connecting a Site; here is the site side of it.

1. Download Site, unpack the zip, run npm install in the folder.
2. Copy .env.example to .env.local and fill in what it names: your KeenAgents host, the chat WebSocket address (from your onboarding details — never the tunnel), the site's public origin, and the client id and secret and api key id and secret the admin handed you. The file is yours alone — never commit it.
3. Start the site (npm run dev; npm run dev-local when your sandbox uses a self-signed certificate) and open a tunnel to it — the tunnel's https address is the site's Origin while it runs on your machine.
4. Give the admin that address: it becomes the Webhook entry's Origin (matched exactly — scheme, host and port) and, with /api/keen-webhook appended, its notification URL. Put the same origin into .env.local and restart the site — it reads its configuration only at start.
5. On the Api Key's page the admin presses Rebuild Resource Cache, then Wake. The site receives its certificate and configuration and switches from its holding page to live: register a consumer, sign in, chat with your agent.

# 1. unpack the zip, then in that folder:
npm install
cp .env.example .env.local        # fill it in — see the list below

# 2. start the site (dev-local when your sandbox uses a self-signed certificate)
npm run dev
npm run dev-local

# 3. make it reachable for the platform's notices (a tunnel, while it runs on your machine)
ngrok http 3000                   # → a public https://… address: your site's Origin

1. In the console, Organization → MCP Accounts → Create: a name, and a role whose write scopes cover spaces, agents, clients, certificates, contracts, webhooks, api keys, cache and MCP consumers. Copy the id and the secret the moment they appear — the secret is shown once.
2. Download Toolkit, unpack the zip, and open a terminal in that folder. Start Claude Code there and approve the one-time prompt: the folder carries the registration of the keen MCP server.
3. Run /keen-install once: it checks Node, ngrok and the assistant, puts the prebuilt keen-validate and keen-deploy on your path and installs the runner.
4. Run /keen-start (or just say hello — the assistant runs it on its first reply) and choose Create new project. A short wizard asks you, one at a time, for the space and agent names, your KeenAgents host, the MCP account id and secret, where the flow project should live, where your copy of the Entanglement site is (none yet? /keen-entanglement-download fetches it), and whether to create a new end-user identity for the bot or reuse one.
5. The assistant then performs the setup end to end — space, agent, the API access chain, the site's configuration and tunnel, the Webhook entry, Rebuild → Wake, an MCP consumer and its token, a first flow validated and deployed — and ends with a test prompt you can run. Everything it created is saved as a project you can reopen with List existing projects; secrets live in one private file inside the toolkit folder.
6. From there, just say what you want built. The assistant writes the flow, checks it, deploys it and runs a real conversation to read the result — and /keen-project-validate re-checks a saved project whenever something looks off.

# unpack the zip, open a terminal IN that folder, start your assistant there
claude                            # approve the one-time prompt that registers the "keen" MCP server

/keen-install                     # once per machine: prerequisites, the two prebuilt tools, the runner
/keen-start                       # every session: the banner → Create new project / List existing projects

/keen-entanglement-download       # no copy of the site yet? fetches it into a folder you name
/keen-project-validate            # later: check a saved project end to end