Deployment

A flow project — your flows and the script code that runs inside them — starts life on your machine. Deployment is how that project reaches the running platform. You build the project and deploy it into a space using that space's deployment token; the platform checks the project, and once it passes, the running system picks it up automatically. There is no restart to schedule and no manual switch to flip — a deployed change goes live within moments.

Deployment is scoped to a space. The space's ID doubles as its project ID, and the deploy client — the Flow Builder extension's Connect → Upload, or the keen-deploy command-line tool from the Keen Mastering Toolkit for headless and CI use — authenticates into that space with the deployment token, so a deploy always lands in exactly one space and can only touch the flows that belong to it.

1. Upload. The deploy client bundles your project exactly as you authored it — the flows/ folder of .flow files, the scripts/ folder, and the tool registry keen-tools.json — and uploads it into the target space, authenticated by the space's deployment token. A wrong or retired token is refused, so only someone holding the current token can deploy. (The agents themselves live in the admin console and point at a flow in the project you deploy.)
2. Build and check. The platform compiles your flows and checks the layout: flows/ must exist and hold at least one .flow file and nothing else (no sub-folders, no stray files); every flow and the tool registry must be valid JSON. A project that fails is rejected with the exact reasons and never goes live.
3. Security scan. Before anything can run, the platform scans the project for unsafe code. A project that fails the scan is rejected and never goes live — this is the gate that lets partner-authored code be trusted at run time.
4. Go live. Once the scan passes, the project is promoted and the running system picks it up on its own. The new version supersedes the previous one: there is one live version per space. A conversation that is mid-run when you deploy keeps its working memory and continues on the new version from its next step — so ship changes that break a flow's shape (renamed entries, removed nodes) at a quiet moment, and expect new runs to use the new version at once.

A deploy is refused, with the reasons, when:

• the bundle has no flows/ or no scripts/ folder;
• flows/ has a sub-folder, a file that is not a .flow, or no .flow at all;
• a flow or the tool registry is not valid JSON;
• the scan finds unsafe code (each finding names the file and line).

A refused deploy leaves the live version exactly as it was. A space accepts one deploy connection at a time: connecting from a second machine takes the connection over, and a connection idles out after a few minutes — the client simply connects again. If two uploads for the same space overlap, the later one wins and the earlier is reported as superseded. Saving a single file after the first deploy pushes just that change; it goes through the same scan, and the platform's own generated files inside the project cannot be edited or deleted by a save.

You deploy from the Flow Builder extension (Connect → Upload), or — for a pipeline or a headless building assistant — with the keen-deploy command-line tool from the Keen Mastering Toolkit, which takes the same three values (instance URL, space id, deployment token) and uploads the same src/ folder. Its companion keen-validate checks a project against the platform's rules before you spend a deploy.

Deployment token

The credential the deploy tool uses to authenticate a deploy into a space. It is generated for you when the space is created, shown read-only on the space's detail page (with a Copy button), and can be re-minted with Reset Token. Re-minting retires the previous token: the next time a client connects with the old value it is refused. A deploy connection that was already open keeps working for a few minutes until it expires, so if the token may have leaked, reset it and wait for that window to pass.

Security scan

Every deploy is scanned before it is allowed to run. The scan is what makes it safe to run your script nodes on the platform: code that does not pass is never promoted, so a rejected deploy leaves the previously running version exactly as it was.

Supersession

A deploy replaces the space's previous project version — there is one live version per space at a time. Re-deploying is the normal way to ship a change; you do not manage versions by hand.

Space = project

The space ID is the project ID. It is what a deploy targets and what chat clients pass as the project identifier at run time, so the same identifier ties your deploy, your agents, and the caller together.

• Keep the deployment token secret and rotate it if it may have leaked — after Reset Token the old value is refused at the next connect (an already-open deploy connection lasts a few more minutes). Distribute the new token to your pipeline right away, or its next deploy fails.
• A deploy that is rejected by the security scan does not affect the running agent — the live version keeps serving until a clean deploy replaces it.
• Deleting a space removes its deployed project along with its agents and their settings — one action clears the whole unit, and there is no undo.
• A newly deployed change is picked up automatically within moments; you do not need to restart anything or take the space out of service to ship.
• After the first deploy, saving your project re-deploys it automatically — your edits keep flowing to the space as you build, and each one is scanned before it can run.