# Multi-Instance Builder Kit Plan

## Decision

The Builder Kit should always use a central control folder, even when there is only one assistant.

Central folder:

```text
/home/user/.builder-kit
```

The first assistant should be treated as the default instance named `main`, not as a one-off install.

This design is now also an **existing-install protection rule**: Builder Kit must not assume it owns the user's standalone OpenClaw setup.

---

## Existing Installation Isolation

Builder Kit must not interfere with any existing Claw/OpenClaw assistant a user already has.

This includes:

- existing `~/.openclaw` runtime folders
- existing assistant workspaces
- existing gateway tokens
- existing gateway ports
- existing standalone assistants, such as Butch

Builder Kit should use its own isolated shared home:

```text
~/.builder-kit
```

Each Builder Kit assistant instance should use its own isolated runtime:

```text
~/.builder-kit/instances/<instance-name>/.openclaw
```

The installer and launcher should avoid writing to `~/.openclaw` unless the user explicitly chooses that path for a separate non-Builder-Kit setup.

---

## Tested Alpha Isolation Pattern

The alpha test confirmed that the first Builder Kit assistant can run separately from an existing assistant.

Tested paths:

```text
BUILDER_KIT_HOME=/home/user/.builder-kit-alpha-test
BUILDER_KIT_INSTALL_ROOT=/home/user/claw-builder-kit-alpha-test
BUILDER_KIT_DEFAULT_INSTANCE=main
BUILDER_KIT_GATEWAY_PORT=19099
```

Tested runtime:

```text
/home/user/.builder-kit-alpha-test/instances/main/.openclaw
```

Confirmed result:

- alpha launcher opened the Builder Kit assistant on port `19099`
- it did not open Butch
- it did not rely on the default `~/.openclaw`
- it used matching token authentication for the selected instance

---

## Planned Structure

```text
/home/user/.builder-kit/shared.env
/home/user/.builder-kit/instances.json
/home/user/.builder-kit/common/help/
/home/user/.builder-kit/logs/
/home/user/.builder-kit/launchers/
/home/user/.builder-kit/instances/main/.openclaw/
/home/user/.builder-kit/instances/builder/.openclaw/
/home/user/.builder-kit/instances/business/.openclaw/
```

---

## Shared Information

Shared information belongs in the central Builder Kit home:

- API keys and provider configuration
- instance registry
- port assignments
- token records or token-generation metadata
- common Builder Kit help
- installer logs
- launcher templates
- version, upgrade, backup, and troubleshooting records

Do not store customer provider keys in git.

Do not package live `shared.env` files for distribution.

---

## Instance-Specific Information

Each assistant instance should have its own isolated runtime:

- OpenClaw runtime
- workspace
- assistant identity and bootstrap files
- sessions and memory
- specialty knowledge base
- specialty tools and settings
- assigned gateway port
- matching gateway token
- assistant name, purpose, and personality

---

## Default Main Instance

```text
name: main
gateway_port: 18999
runtime: /home/user/.builder-kit/instances/main/.openclaw
```

Note: port `18999` is only a default. If another assistant is already using that port, Builder Kit must use a different available port.

---

## Port Strategy

Use a reserved local range and track assignments in `instances.json`.

Example plan:

```text
main      gateway 18999
builder   gateway 18998
business  gateway 18997
writing   gateway 18996
research  gateway 18995
```

The installer and launcher should check both:

- the Builder Kit instance registry
- actual live port availability

The launcher must not assume that a running gateway belongs to Builder Kit just because the port responds.

---

## Launcher Requirements

The Windows launcher should:

- detect the WSL home directory
- support `BUILDER_KIT_INSTALL_ROOT`
- support `BUILDER_KIT_HOME`
- support `BUILDER_KIT_DEFAULT_INSTANCE`
- support configurable `BUILDER_KIT_GATEWAY_PORT`
- support matching token auth
- export `BUILDER_KIT_HOME` and `OPENCLAW_HOME` for every OpenClaw command
- set `gateway.port` in the selected instance config
- set `gateway.auth.mode`
- set `gateway.auth.token`
- start the gateway with the same port and token
- run `dashboard --no-open` without unsupported `--port`
- open the generated dashboard URL

---

## Installer Requirements

The installer should:

- initialize the central Builder Kit home
- create or reuse `shared.env`
- validate provider keys without printing them
- create the default `main` instance under `~/.builder-kit/instances/main`
- set `OPENCLAW_HOME` to the selected Builder Kit instance path
- avoid writing to the user's standalone `~/.openclaw`
- copy/sync the pinned local OpenClaw tree into the install root
- configure `google/gemini-2.5-flash-lite` as the current preferred default model

---

## Near-Term Recommendation

Do not fully build multi-instance creation yet.

Current priority:

1. Keep the default `main` instance stable.
2. Keep launcher/runtime isolation working.
3. Keep documentation aligned with tested behavior.
4. Avoid disturbing existing standalone assistants.

Add multi-instance creation later through a separate script or installer mode.

---

## Open Follow-Up

Later, `instances.json` should store each instance's assigned port, runtime path, display name, and token metadata so launchers do not need to guess.
