Skip to main content

AI Spaces

An AI Space is a container that holds Agents. Each Space corresponds to one project — think of it as a folder on disk that has permissions to store custom client code.

Why Spaces exist​

  • Each AI Space gets its own VS Code project, so flows for different products live in different repos.
  • Better maintenance: per-space code, per-space access control.
  • The Space is the boundary the runtime uses when locating files for execution.

Spaces list page​

Standard table layout — list of spaces, edit button per row.

Space edit page (three sections)​

When you open a Space for editing, you see three sections:

1. Space (form)​

Two fields:

  • Title — clear, memorable name (e.g. Customer Support Bot, Content Generator, Data Analysis Hub).
  • Description — what the space does and its primary purpose. Include key features, use cases, what makes it unique.

2. Agents​

A list of every agent assigned to this Space. A Space may have many agents; an Agent belongs to exactly one Space (see agents.md).

3. Space Code Snippets​

A helper that gives you everything you need to wire up a VS Code project against this Space. Three pieces:

Step 1 — Create the project​

npx keen-project-create [the-name-of-the-project]

(Requires the Keen Extension installed.)

Step 2 — package.json deploy command​

Copy the snippet into your project's package.json under scripts. This is what ships your code to the Keen server:

"deploy": "keen-builder --token=<TOKEN> --space=<SPACE_ID>"

The --token and --space values are pre-filled by the snippets page for your space.

Step 3 — .vscode/launch.json for the debuggers​

The sandbox exposes two Chrome DevTools Protocol (CDP) debug proxies — one for script nodes on port 7100, and one for the flow debugger on port 7101. Add an attach configuration for each:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Keen — Script nodes",
            "type": "node",
            "request": "attach",
            "address": "[THE DOMAIN OF THE INSTANCE]",
            "port": 7100,
            "timeout": 30000,
            "skipFiles": ["<node_internals>/**"],
            "sourceMaps": true,
            "localRoot": "${workspaceFolder}/src",
            "remoteRoot": "/app/projects/[GENERATED ID OF THE SPACE]"
        },
        {
            "name": "Attach to Keen — Flow debugger",
            "type": "node",
            "request": "attach",
            "address": "[THE DOMAIN OF THE INSTANCE]",
            "port": 7101,
            "timeout": 30000,
            "skipFiles": ["<node_internals>/**"],
            "sourceMaps": true,
            "localRoot": "${workspaceFolder}/src",
            "remoteRoot": "/app/projects/[GENERATED ID OF THE SPACE]"
        }
    ]
}
  • Port 7100 attaches a source-level debugger to your script nodes — you only ever pause inside your own scripts/*.js.
  • Port 7101 attaches to the flow debugger probe.
  • Debugging is sandbox-only. Production runs the same flows with no debugger attached.

Step 4 — keen.json at the project root​

{
    "keen_server": "https://[THE DOMAIN OF THE INSTANCE]",
    "entry": "src",
    "dist": "dist"
}

Creating a Space​

AI Spaces → Create. Fill in Title and Description. After submit, you're redirected to the edit page where Agents and Space Code Snippets become available.

  • Agents — agents live inside a Space and are how Consumers interact with that Space.
  • Consumers — Consumers are granted access per-Space.
  • Keen Extension — the editor side of the Space's project.