JOLACODE / FIELD GUIDE

From first launch
to first change.

JolaCode runs on your machine. It brings a coding assistant, file editor and terminal into one workspace. This guide covers the version-one developer release.

1. Install and launch

You need Python 3.12 or newer and Node.js 22.12 or newer. Download and unpack the source release, open a terminal in its folder, then run:

make venv
cd web && npm ci && npm run build
cd ..
./start.sh desktop

The first desktop launch installs Electron. The desktop shell is verified on macOS; a signed, self-contained installer is not included. To use your browser instead:

./start.sh dev

Open the local address printed by the backend. The development port is read from the included JCDS manifest. Stop a browser-mode server with Control-C in its terminal; quit the desktop application to stop the backend it started.

2. Unlock your local workspace

Set your own JOLACODE_AUTH_TOKEN in the generated .env file and restart. Enter that private key at the local access gate. Keep the application on loopback; never publish your key.

3. Choose local or OpenRouter

Open Settings → Model. Both options remain available, and each remembers its own model settings.

• Local model: enter your running server’s model ID and loopback endpoint, normally http://127.0.0.1:8080/v1. Save and use provider. JolaCode does not download weights or start inference automatically. If the server is stopped, Settings shows it as unavailable.
• OpenRouter: enter an explicit model ID available to your account and your own API key, then save. A missing key produces a clear error. Model availability and pricing can change; check the provider before making requests.

Profiles persist in ~/.jolacode/providers.json with file permissions restricted to your account. Keys are never returned to the browser after saving. Hosted requests send the included code and command output to OpenRouter and its selected provider. Only use workspaces you are permitted to share.

The historical local model was Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf. It is a separate multi-gigabyte download, not bundled with the app. Hardware suitability and performance depend on available memory and context settings.

4. Open a project

Choose a folder using the workspace picker, or set JOLACODE_WORKSPACE_ROOT before launch. Start with one small, concrete request. The assistant can read, search and edit files and run allowed commands. Follow the streamed transcript to see what happened.

5. Review and recover

Manual mode asks before file edits and commands. Review each proposed action. The terminal is a separate, unsandboxed shell for you, not a tool available to the model.

File changes appear as diffs. Revert a file to restore its pre-run content. Closing a conversation archives it, preserving the transcript and original-file snapshots.

6. Know where things live

Chats, audit logs and workspace memory are stored in ~/.jolacode. Set JOLACODE_STATE_DIR to use a different location. Browser preferences and local access state live in browser storage. JolaCode does not migrate legacy Cologic or Researcher data.

When something is missing

• The UI loads but chat does not respond: check your model server, endpoint, model identifier and key.
• The UI has not been built: run cd web && npm ci && npm run build, then restart.
• You changed backend configuration: restart the Python process; refreshing the page alone is not enough.
• Desktop installation is incomplete: run node scripts/install-electron.cjs from the project root, then launch again.

Release boundaries

Version one is a local developer release. The inherited iOS application, Windows launcher, hosted agent backend and signed installers are not part of the verified release. No hosted coding service or paid account is required.