Installation

Installation

AICS - KSP Chat Bridge has two halves: the plugin that lives in your KSP GameData folder, and the bridge, the program that does the thinking. Since version 0.1.1 CKAN and the release zip install both: the bridge comes ready to run as GameData/KSPChatBridge/Bridge/AICSBridge.exe, so you don't need Python or the source code. Plan on about ten minutes, most of which is downloading an AI model if you go local.

[COMMS] Bill (Eng): Two halves, one mod. Like a rocket and its launch clamps. Except you keep both.

What you need

• Kerbal Space Program 1.12.x (it's developed on 1.12.5).
• kRPC 0.6.x. Required. The bridge talks to KSP only through kRPC.
• MechJeb2 + kRPC.MechJeb. Optional but recommended. Rocket ascent, orbital maneuvers, targeted landings and docking use MechJeb. Planes, propeller craft, helicopters, the crew and the dashboard all work without it; the AICS menu just shows no MJ in grey.
• Windows (the bundled bridge is a Windows exe; on other systems run the bridge from source, see below).
• An AI backend: LM Studio for a local model, or an API key for a cloud service. See below.

Step 1: Install the plugin

With CKAN (recommended)

Search for AICS - KSP Chat Bridge (identifier KSPChatBridge). CKAN pulls in kRPC automatically and offers MechJeb2 and kRPC.MechJeb as recommendations. Say yes to those unless you have a reason not to.

CKAN listing is pending review at the time of writing. If you can't find it yet, use the manual install.

Manually

1. Download KSPChatBridge-<version>.zip from the Releases page.
2. Unzip it into your KSP folder so you end up with GameData/KSPChatBridge/Plugins/KSPChatBridge.dll and GameData/KSPChatBridge/Bridge/AICSBridge.exe.
3. Install kRPC yourself (and, if you like, MechJeb2 and kRPC.MechJeb; kRPC.MechJeb's DLL goes in GameData/kRPC).

Step 2: Set up kRPC

The first time you start KSP with kRPC, open its server window and:

• turn on auto-start for the server, and
• turn on auto-accept new clients (otherwise KSP pops up a "new client" question every time the bridge connects).

Defaults are fine for everything else: address 127.0.0.1, RPC port 50000, stream port 50001. If you change them, set KRPC_ADDRESS, KRPC_RPC_PORT and KRPC_STREAM_PORT for the bridge to match (see Settings).

Step 3: The bridge (nothing to do)

The plugin starts the bundled AICSBridge.exe in the background (no window) when KSP starts, if a bridge isn't already running, and stops it when KSP quits. If anything goes wrong, you'll see [bridge] ... lines in the chat window and details in GameData/KSPChatBridge/PluginData/logs/bridge.log.

The bridge keeps your data in GameData/KSPChatBridge/PluginData/: API keys (.env), settings, playstyle notes, crew personalities and logs. Updates (and CKAN) leave that folder alone. Some antivirus tools are suspicious of PyInstaller-built programs in general; if yours complains, see Build it yourself below or run from source.

From source (developers, or if you'd rather not run an exe)

1. Install Python 3.12 from python.org (tick "Add python.exe to PATH").

2. Get the code: git clone https://github.com/zernon916/KSPChatBridge.git, or download the repository as a zip and unpack it somewhere permanent, for example C:\Games\KSPChatBridge.

3. In that folder run:

   python -m pip install --user -r requirements.txt
   

4. Start KSP once so the plugin creates GameData/KSPChatBridge/PluginData/bridge.cfg. Quit KSP and set bridge_dir to the folder from step 2:

   autostart = true
   stop_on_quit = true
   bridge_dir = C:\Games\KSPChatBridge
   python = python
   

   If python isn't on your PATH, put the full path to python.exe on the python = line. With bridge_dir set, the plugin runs python run_bridge.py serve from your checkout instead of the bundled exe, and the bridge keeps its data (.env, logs, ...) in that folder. Leave bridge_dir empty to go back to the exe. You can also start it by hand with start_bridge.cmd or python run_bridge.py serve.

Transparency: build it yourself

The source code is public on GitHub, and AICSBridge.exe is built from exactly that source (run_bridge.py and the kspchat folder) with PyInstaller, nothing added. To build it yourself, run this in a clone of the repository:

powershell -ExecutionPolicy Bypass -File tools\package_release.ps1

It sets up a private Python environment with the packages from requirements.txt plus PyInstaller, builds the plugin and the exe, and writes the release zip plus its SHA-256 checksums to dist\. The PyInstaller step on its own is:

python -m PyInstaller --noconfirm --clean --onefile --windowed --name AICSBridge --icon assets\AICSBridge.ico --add-data "playstyle_notes.example.md;." --collect-submodules kspchat run_bridge.py

Every GitHub release lists the SHA-256 checksums of the zip and of AICSBridge.exe, so you can check your download. A rebuild won't match those hashes byte for byte (PyInstaller builds aren't reproducible), so to verify the code itself, read the source or run from source.

Step 4: Pick an AI

Small, direct orders like "gear down", "heading 090" or "throttle 60" are understood by the bridge itself and never need the AI (see Captain's Orders). Anything conversational ("can we make it to the Mun with this?") goes to the AI you pick.

Local: LM Studio (free, private, needs a GPU)

Step-by-step setup for LM Studio and Ollama, plus which model to pick for your graphics card: Local AI Setup.

1. Install LM Studio and download a model with tool-calling support.
2. Load it. The bridge uses whichever model is loaded in LM Studio. If nothing is loaded, it starts the LM Studio server on port 1234 and loads qwen/qwen3.5-9b with a 16k context through LM Studio's lms command-line tool.

Model notes from our own testing (KSP running at the same time, 10 GB graphics card):

Model	How it did	Graphics memory
qwen/qwen3.5-9b	the fallback default; picked the right tool 8 out of 8 times	about 6 GB
google/gemma-4-e4b	also 8/8, a bit faster, the lightweight pick	about 4.7 GB
qwen3-4b-instruct-2507	fast and loads in seconds; 6/8, sometimes answers without checking	about 5.4 GB

Avoid models that can't do proper tool calls: they'll chat nicely and fly nothing. KSP plus a local model is a lot for one graphics card; if KSP stutters, try the smaller model or a cloud backend. You can switch models from the chat with /model (see Settings).

Sidry: Smaller model, smaller brain. Still smarter than Jeb. Don't tell Jeb.

Cloud (and other) backends: Groq, Gemini, OpenAI, OpenRouter, Hugging Face, Ollama, or anything OpenAI-compatible

The easy way is in game: open AICS -> Settings, pick the backend, paste your key into the API key field and press Save. The bridge stores it in a .env file (GameData/KSPChatBridge/PluginData/.env with the bundled exe, the repository folder when running from source) and starts using it immediately, no restart. The field shows only the last four characters afterwards.

Or write the .env file yourself, one line per key, in that same place (PluginData, or next to run_bridge.py from source). Only add the ones you use:

GROQ_API_KEY=your-groq-key-here
GEMINI_API_KEY=your-gemini-key-here
OPENAI_API_KEY=your-openai-key-here
OPENROUTER_API_KEY=your-openrouter-key-here
HF_TOKEN=your-hugging-face-token-here

Then restart the bridge (quit and restart KSP; from source you can also run powershell -File tools\restart_bridge.ps1).

Backend	Key	Default model	Notes
Groq	GROQ_API_KEY (free at console.groq.com)	openai/gpt-oss-120b	Fast. The free tier's tokens-per-minute cap is tight; the bridge waits and retries when it's hit.
Gemini	GEMINI_API_KEY or GOOGLE_API_KEY (free at aistudio.google.com)	gemini-flash-latest	Generous free tier on the Flash models.
ChatGPT (API)	OPENAI_API_KEY	gpt-4.1-mini	Paid.
OpenRouter	OPENROUTER_API_KEY	openrouter/free	Free models, about 50 requests a day.
Hugging Face	HF_TOKEN (needs "Inference Providers" permission)	openai/gpt-oss-120b:fastest	Little or no free credit.
Ollama	none (ollama serve on this PC)	first installed model	Local alternative to LM Studio. OLLAMA_MODEL picks one. See Local AI Setup.
Custom	CUSTOM_AI_URL, CUSTOM_AI_MODEL, optional CUSTOM_AI_KEY	whatever you set	Any OpenAI-compatible server: Mistral, DeepSeek, xAI, Anthropic's compatibility endpoint, a local vLLM or llama.cpp.

Change a default model with the matching variable, for example GROQ_MODEL=... or GEMINI_MODEL=.... A backend without a key doesn't break anything; it just tells you which key to add. Free tiers change often and may use your prompts for training, so check the provider's terms.

Never share your .env file or paste keys into chat. It's ignored by git, so it won't end up in a commit.

Switching backends

In game: AICS -> Settings -> AI backend (dropdown), or type /ai groq, /ai gemini, /ai local and so on in the chat. /ai on its own lists them. The choice is remembered.

Check it works

Start KSP, load a save, put something on the launch pad, press Alt+K and type:

report

Your pilot should answer with altitude, speed, heading and fuel. If you get nothing or a [bridge] error, head to Troubleshooting.

[INTERCOM] Bob (Sci): It talked back! Is it alive? Should I name it? I'm naming it.

Next: Quick Start.