SolonCode in 15 Minutes: Install, Configure a Model, and Land Your First Reviewable Diff

If your experience with coding agents is "it installed and it chats," you haven't had a first success yet — not the kind you can screenshot and show your team. Most getting-started posts stop at "I talked to it once," which doesn't tell you whether the tool can actually touch a real repository. This guide fixes that with a different yardstick.

SolonCode is an open-source coding agent written in Java, built on the Solon AI framework, and designed to run on Java 8 through Java 26. One honest caveat up front: its prompt system is built around Chinese-first interaction (the official docs state it's not recommended if you can't work with Chinese prompts) — which makes it an interesting pick for Chinese-speaking teams and for developers who want a model-agnostic agent they can run on their own gateway. Everything below is verified against the official docs as of SolonCode v2026.8.3.

What "first success" actually means here

Most short tutorials leave you with three failure modes:

• The model won't connect, and you can't tell whether that counts as a failure or a misconfiguration.
• You chatted, but the agent never modified a real file, so you still don't trust it.
• Something breaks and you don't know whether to check the API key, the proxy, or the workspace path.

So this guide sets three concrete pass criteria — L1, L2, L3 — and gives you a fixed path: install → configure a model in the Web UI → land a small reviewable change. The goal isn't to learn all of SolonCode in 15 minutes; it's to earn one screenshot-worthy first success that you can explain to a colleague.

Prerequisites (2-minute self-check)

Item	Requirement	How to verify
JDK	Java 8 or higher (official support: Java 8 ~ 26)	java -version prints a version
OS	macOS / Linux / Windows (Harmony PC also supported)	you can run a shell / PowerShell
Model API	any LLM endpoint in OpenAI / Anthropic / Gemini / Ollama-compatible form	you have apiUrl, apiKey (if needed), and a model name

SolonCode does not bundle or bind to any vendor — you bring your own model (BYOK) or point it at an internal gateway. Without a working model configuration, the process starts but that's not a first success.

Nice-to-haves (not blockers): Git (helps you view diffs in the Web UI), a small real project directory (the launch directory becomes the workspace), and stable network / correct proxy settings.

Install: one command, then verify the version

macOS / Linux / Harmony PC:

curl -fsSL https://solon.noear.org/soloncode/setup.sh | bash

Windows (PowerShell):

irm https://solon.noear.org/soloncode/setup.ps1 | iex

Re-running the same install command updates the program while keeping your config and definition files. Program and user-level config default to ~/.soloncode/ (Windows: .soloncode under your home directory).

Minimum success check:

soloncode version

If it prints a version string, you're good to continue. If you get command not found: re-run the installer, check that soloncode is on your PATH, and open a new terminal window (PATH changes often require a fresh shell).

For offline / intranet installs, the official path is: download soloncode-cli-bin-*.tar.gz from Gitee Releases on a networked machine, copy it over, extract, and run install.sh / install.ps1. For your first success, do it online first.

Configure your first model in the Web UI

The officially recommended path for new users is the Web settings page — no need to hand-edit config files on day one.

soloncode web 0

The web command behavior: soloncode web uses default port 4808; soloncode web 0 picks an available port automatically (handy when 4808 is taken); soloncode web 1212 binds a specific port. The terminal prints something like Web interface: http://localhost:xxxxx/.

Then:

1. Open Settings → LLM (or equivalent) in the Web UI.
2. Add a model with at least: API URL (apiUrl), API key (if the provider needs one), and model name (exactly as shown in your provider console).
3. Use the "Test connection" button — the official docs emphasize it works.
4. Make sure the model is enabled and appears in the conversation's model list.

Config lands in settings.json: user-level at ~/.soloncode/settings.json (shared across projects), workspace-level at .soloncode/settings.json (project-specific). Workspace settings are read after user-level and can override or extend them. Security note: keys are secrets — never commit settings.json to Git; use a secret manager or per-developer local config for team setups.

Model-configuration success checklist:

• [ ] Test connection passes
• [ ] A "hello" message gets a normal model reply (not timeout / 401 / empty)
• [ ] The current model name shows near the UI title (e.g. Model:deepseek-v4-flash — whatever you configured)

Only now are you "installed and talking." That's not yet a coding success.

Enter your project (workspace = launch directory)

The official docs recommend starting inside the project root; the launch directory becomes the current workspace.

cd /path/to/your-project
soloncode web 0
# or
soloncode cli

No project yet? You can explore conversation and file generation in any empty directory, but L2/L3 strongly benefit from a real repository — otherwise your "demo" has no persuasive power. When the CLI starts, the tips line looks like:

Tips: (esc) interrupt | /(tab) command | $(tab) skill | @(tab) agent

esc interrupts; commands / skills / subagents have tab completion. Natural language is enough for your first success.

The three-level task: L1 → L2 → L3

Suggested time budget (roughly 15 minutes total, model speed dependent): L1 ~3 min, L2 5–7 min, L3 5–7 min. If the model is slow or the repo is large, do L2 thoroughly rather than skipping review and rushing L3.

L1 — greeting and project scan

Send (in Chinese — this is the product's first-class interaction language):

请先阅读当前项目结构，告诉我：
1）这是什么技术栈；
2）构建命令和测试命令分别可能是什么；
3）如果存在 .soloncode/CODE.md，请优先参考它。
不要修改任何文件。

If the project has no CODE.md yet, the official quick start suggests continuing with:

请根据当前项目生成 .soloncode/CODE.md，包含构建命令、测试命令和代码修改注意事项。

L1 pass criteria (all must hold):

• [ ] The tech-stack description roughly matches the repo (honest "needs further confirmation" is allowed)
• [ ] Build/test entry points are stated or inferred (or honestly reported as not found)
• [ ] When you asked for no file changes, git status shows no unexpected dirty files

Common L1 failures: not starting in the project root; model misconfigured; empty repo or unreadable permissions.

L2 — a small change + explain the diff (first "demoable" step)

Task A (docs, lowest risk):

请帮我检查 README 中是否有过时的安装说明，只修改文档，不改业务代码。
完成后：
1）列出改了哪些文件；
2）用简短条目说明每处为什么改；
3）不要提交 Git，交给我人工确认。

Task B (code, still small):

请新增一个简单的健康检查接口（或补全已有 health 相关说明），范围尽量小。
限制：
- 不要做大范围重构；
- 不要改无关模块；
- 改完说明如何本地验证；
- 不要 git commit。

L2 pass criteria:

• [ ] Pointable file changes exist (visible in Web Git Diff or git diff)
• [ ] The agent explains in natural language what changed and why
• [ ] You scanned the diff yourself — no keys, no huge unrelated reformatting, nothing deleted by accident
• [ ] You can describe this change to a colleague in one sentence (that's "demoable")

Human review checklist (mandatory, 30s–2min): did the change exceed your allowed scope? Any API keys, intranet addresses, or passwords? Any lockfiles or generated artifacts modified? Can you actually run the verification steps yourself?

This is where SolonCode's value starts showing: it advances the implementation; you guard the boundary and the merge decision.

L3 — a constrained small feature (must be reviewable)

Only after L2 passes. The prompt template includes the four elements the official docs emphasize: goal, scope, constraints, verification.

目标：{one sentence describing the deliverable behavior, e.g. 为用户模块增加按邮箱查询的只读接口}
范围：只允许修改 {包名/目录} 下的文件；文档仅在必要时更新 README 一小节。
限制：
- 不要改变既有接口的返回结构；
- 不要升级依赖版本；
- 不要执行删除文件、强制推送、修改 CI 密钥类操作；
- 不要 git commit / push。
验证：
- 修改后运行：{e.g. mvn -pl xxx test 或 npm test 或具体命令}；
- 若无法运行测试，请说明阻塞原因与你已做的静态检查。
交付：
1）变更文件列表；
2）行为说明（给 reviewer 看）；
3）你执行过的命令与结果摘要；
4）残留风险（若有）。

L3 pass criteria:

• [ ] All four deliverables present (list / explanation / command results / risks)
• [ ] The diff is reviewable by a third person (no mysterious large-scale reshuffling)
• [ ] Verification commands were run, or the blocker is credible
• [ ] You explicitly decide: accept / partially accept / roll back — the decision stays with a human

L3 explicitly should NOT be: whole-site rewrites, multi-service migration in one shot, "refactoring as a side effect" without tests, production data operations, permission escalation, key rotation — and never treat "one conversation" as "can merge without review."

Screenshot checklist (for your team channel)

Four to six screenshots beat a paragraph of adjectives:

#	What to capture	What it proves
1	soloncode version output	installed
2	Web Settings → LLM + test connection success	model wired up
3	L1's reply about project structure	reads the workspace
4	Git Diff or git diff snippet (mask sensitive info)	actually changed code/docs
5	Agent's change summary + your verification output	reviewable and verifiable
6	(optional) Web file tree + workspace path	right directory

Top 10 failures and where to look first

Debugging hint from the official docs: check on-disk logs under the workspace .soloncode/logs/; docs: logs & troubleshooting.

#	Symptom	Check first	Fix
1	soloncode command not found	PATH, installed for current user	reinstall; new terminal; confirm ~/.soloncode/bin
2	Java not 8+ / missing	java -version	install any JDK 8–26 release
3	Web UI won't open	terminal URL; port occupied	use web 0 or another port; open the printed address manually
4	Model connection fails	apiUrl / apiKey / model name	compare character-by-character with provider console; check proxy
5	401 / 403	key permissions & quota	rotate key; check plan and IP restrictions
6	Timeout / spinner forever	network, proxy, cross-border path	switch to reachable gateway; increase timeout; try a lighter model
7	Chats but won't touch files	prompt forbade changes; permission / sandbox	L2: explicitly allow target paths; check tool permissions in settings
8	Modified wrong directory	launch dir ≠ repo root	cd to the root containing pom.xml / package.json / .git before starting
9	Ignoring instructions	language expectations	the product is Chinese-prompt-driven; write constraints in Chinese
10	Weird behavior / stale state	long or old session context	start a new session; complex tasks → check task state under .soloncode/sessions/

Mental note on safety: HITL (human-in-the-loop) switches like hitlEnabled exist in settings. During your first success, keep the default conservative posture — don't disable safety-related limits just to go faster on a production repo.

After first success: only two compounding steps

Don't dive straight into Loop / multi-agent / IM binding. The smallest next loop is:

1. Write a 10-line project AGENTS.md at .soloncode/AGENTS.md (workspace beats user-level ~/.soloncode/AGENTS.md). Minimal copy-paste template:

# 本项目 Agent 规约（精简）

## 必须
- 改代码前先读相关文件；小步修改
- 优先运行项目既有测试命令（见 CODE.md）
- 完成后给出：变更列表、验证方式、风险

## 禁止
- 无确认不删文件、不 force push、不改密钥与 CI 密钥
- 不引入与任务无关的依赖升级
- 不把 API Key 写进仓库

## 技术偏好
- 语言/框架：{填写}
- 代码风格：与现有文件保持一致

The official advice: keep it short so it doesn't eat your context; state identity, boundaries, and workflow clearly.

2. Install exactly one Skill. Either via Web Settings → Skill Market (browse, read the description, then install to global or workspace pool), or manually: drop a directory containing SKILL.md into ~/.soloncode/skills/ or .soloncode/skills/. Trigger it with:

请使用 {技能名} 按它的规约帮我完成 {一件具体事}。

CLI skill completion: $(tab). Principle: read the SKILL.md scenario and permissions before installing. More skills ≠ stronger agent; more relevant skills = stronger agent. Official skills doc: agent skills.

Boundaries: what is NOT first success, and when to stop

Not first success yet: you only opened the web page and the model test fails; you only chatted and never produced a reviewable diff in a real repo; you have a diff but never looked at it and can't explain it.

Stop for today if: the target is a production main branch with no tests and no one available to review; the ask is architecture-level rewrite; or you have no legitimate model access path (account / gateway / compliance).

SolonCode is a delegatable coding agent, not an auto-disclaimer machine. People own direction, boundaries, and merge; the agent advances within the boundary.

The 15-minute path (one page)

1. java -version            # 8+
2. curl ...setup.sh | bash  # or irm ...setup.ps1 | iex
3. soloncode version
4. soloncode web 0
5. Settings → LLM → Add model → Test connection → say "你好"
6. cd your-project && soloncode web 0
7. L1: scan the project (no file changes)
8. L2: small change + you review the diff
9. (optional) L3: constrained small feature + verification commands
10. Write a 10-line .soloncode/AGENTS.md or install one skill

Why this matters

First success isn't about faith in AI; it's about four real things: a real environment (JDK + command on PATH), a real model (test the connection, don't just save the form), a real task (a reviewable small change in the project root), and real review (a human reads the diff and clicks merge).

When you can repeat L2 reliably, SolonCode stops being "another chat window" and becomes the onboarding day of a digital employee in your workflow. The next steps — model routing & cost (series B2), codifying specs into AGENTS.md (series D3), or remote delegation via IM (series C2) — all build on the pass criteria above.

Try it now: run the first 8 steps of the one-page path and keep the L2 diff screenshot. That's the most honest manual SolonCode can give you.

---

References (all official): Repository · Docs entry · Quick start: install to first conversation · Install / update / uninstall · Settings & Web UI · Web interaction mode · Workspace & AGENTS.md / CODE.md · Skills · Logs & troubleshooting · Offline releases (Gitee)