Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(cli): setup-dsh — configure DeepSeek Harness in one command (#995)

Tashfeen1a0ce48280d3
diff --git a/README.md b/README.md
index 7ed2277c..0da93f6a 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,7 @@ The full, always-current list lives at **[freellmapi.co/models](https://freellma
<td align="center"><img src="repo-assets/agents/cursor.png" width="44" alt="Cursor"><br/><b>Cursor</b></td>
<td align="center"><img src="repo-assets/agents/zed.png" width="44" alt="Zed"><br/><b>Zed</b></td>
<td align="center"><img src="repo-assets/agents/jetbrains.png" width="44" alt="JetBrains AI"><br/><b>JetBrains AI</b></td>
+<td align="center"><img src="repo-assets/agents/deepseek-harness.png" width="44" alt="DeepSeek Harness"><br/><b>DeepSeek Harness</b></td>
</tr>
</table>
@@ -132,7 +133,7 @@ The full, always-current list lives at **[freellmapi.co/models](https://freellma
</div>
-Most of these configure themselves with one command — `npx freellmapi setup-claude`, `setup-codex`, `setup-aider`, and ten more generators that fetch your live catalog, back up existing config, and never clobber what's already there. Claude Code and Codex also get zero-persistence launchers (`freellmapi launch`, `freellmapi launch-codex`) that inject credentials into the child process only. Zed and JetBrains AI connect through the opt-in [Ollama emulation](docs/clients.md#ollama-clients); Gemini CLI speaks its native wire on `/v1beta`.
+Most of these configure themselves with one command — `npx freellmapi setup-claude`, `setup-codex`, `setup-aider`, `setup-dsh` (DeepSeek Harness), and ten more generators that fetch your live catalog, back up existing config, and never clobber what's already there. Claude Code and Codex also get zero-persistence launchers (`freellmapi launch`, `freellmapi launch-codex`) that inject credentials into the child process only. Zed and JetBrains AI connect through the opt-in [Ollama emulation](docs/clients.md#ollama-clients); Gemini CLI speaks its native wire on `/v1beta`.
Per-tool recipes, the setup CLI reference, revocable URL tokens for headerless clients, and the MCP server all live in **[Clients & coding agents →](docs/clients.md)**
@@ -213,6 +214,7 @@ Every generator supports `--dry-run`, creates a timestamped backup before changi
| Goose | `setup-goose` | `/v1` |
| Qwen Code | `setup-qwen` | `/v1` (or native `/v1beta`) |
| Roo / Kilo / Crush | `setup-roo` / `setup-kilo` / `setup-crush` | `/v1` |
+| DeepSeek Harness | `setup-dsh` | `/v1` |
| Cursor | `setup-cursor` guide | public `/v1` URL |
FreeLLMAPI is local-first and single-user by design. Your provider keys stay in your SQLite database, encrypted at rest, and requests go from your machine to the upstream providers you enabled.
diff --git a/cli/README.md b/cli/README.md
index 1984ee67..5fa9f291 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -26,6 +26,7 @@ dashboard (or the tray popover in the desktop app).
| `setup-roo` | Roo Code |
| `setup-kilo` | Kilo Code |
| `setup-crush` | Crush |
+| `setup-dsh` | DeepSeek Harness (`dsh`) |
| `setup-cursor` | Cursor |
| `setup-generic` | Any OpenAI-compatible client |
| `launch` | Run Claude Code with credentials injected into the child process |
diff --git a/cli/package.json b/cli/package.json
index 22aabce8..23bfdc8a 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -57,7 +57,8 @@
"node": ">=20.18.0 <25.0.0"
},
"dependencies": {
- "jsonc-parser": "^3.3.1"
+ "jsonc-parser": "^3.3.1",
+ "yaml": "^2.9.0"
},
"devDependencies": {
"@types/node": "^24.12.2",
diff --git a/cli/src/__snapshots__/tools.test.ts.snap b/cli/src/__snapshots__/tools.test.ts.snap
index 3093adfe..b7dc3861 100644
--- a/cli/src/__snapshots__/tools.test.ts.snap
+++ b/cli/src/__snapshots__/tools.test.ts.snap
@@ -240,6 +240,60 @@ exports[`tool generators > setup-cursor has stable golden output 1`] = `
}
`;
+exports[`tool generators > setup-dsh has stable golden output 1`] = `
+{
+ "files": [
+ {
+ "format": "yaml",
+ "path": "/home/tester/.dsh/settings.yaml",
+ "value": {
+ "agent-default-model": {
+ "model": "fast-coder",
+ "provider": "freellmapi",
+ "reasoningEffort": undefined,
+ },
+ "llm-pi-ai": {
+ "providers": {
+ "freellmapi": {
+ "api": "openai-completions",
+ "apiKeyEnv": "FREELLMAPI_API_KEY",
+ "baseURL": "http://localhost:3000/v1",
+ "displayName": "FreeLLMAPI",
+ "models": [
+ {
+ "contextWindow": 131072,
+ "id": "fast-coder",
+ "maxTokens": 8192,
+ "name": "Fast Coder",
+ },
+ {
+ "contextWindow": 262144,
+ "id": "reasoning-model",
+ "maxTokens": 8192,
+ "name": "Reasoning Model",
+ },
+ ],
+ },
+ },
+ },
+ },
+ },
+ {
+ "content": "FREELLMAPI_API_KEY=freellmapi-test-key
+",
+ "format": "env",
+ "path": "/home/tester/.dsh/.env",
+ "sensitive": true,
+ },
+ ],
+ "notes": [
+ "Start DeepSeek Harness with: npx @deepseek-ai/dsh web — freellmapi/fast-coder is the default model.",
+ "Settings are hot-reloaded, so a running dsh picks this up on its next request.",
+ "Models are declared text-only; give a vision model \`input: [text, image]\` under freellmapi.models in settings.yaml to send it images.",
+ ],
+}
+`;
+
exports[`tool generators > setup-generic has stable golden output 1`] = `
{
"files": [],
diff --git a/cli/src/config-files.test.ts b/cli/src/config-files.test.ts
index 8a63642c..02173cce 100644
--- a/cli/src/config-files.test.ts
+++ b/cli/src/config-files.test.ts
@@ -183,6 +183,81 @@ describe('safe config writes', () => {
expect(first.match(/^GOOSE_MODEL:/gm)).toHaveLength(1);
});
+ it('deep-merges structured YAML and retains sibling routes and comments', () => {
+ // DeepSeek Harness keeps every provider under one `llm-pi-ai.providers`
+ // dict. The marked-block YAML merge removes whole top-level keys it
+ // re-emits, which here would delete the user's other providers; the
+ // structured merge must touch only the path it sets.
+ const existing = [
+ '# my settings',
+ 'llm-pi-ai:',
+ ' providers:',
+ ' anthropic:',
+ ' # keep me',
+ ' apiKeyEnv: ANTHROPIC_API_KEY',
+ ' freellmapi:',
+ ' baseURL: http://old:1/v1',
+ ' models:',
+ ' - id: stale',
+ 'agent-default-model:',
+ ' provider: anthropic',
+ ' model: claude-sonnet-4-5',
+ ' reasoningEffort: high',
+ 'other: { a: 1 }',
+ '',
+ ].join('\n');
+ const file = {
+ path: '/tmp/settings.yaml',
+ format: 'yaml' as const,
+ value: {
+ 'llm-pi-ai': {
+ providers: {
+ freellmapi: {
+ baseURL: 'http://localhost:3001/v1',
+ models: [{ id: 'auto' }],
+ },
+ },
+ },
+ 'agent-default-model': {
+ provider: 'freellmapi',
+ model: 'auto',
+ reasoningEffort: undefined,
+ },
+ },
+ };
+ const once = renderFile(file, existing);
+ expect(once).toContain('# my settings');
+ expect(once).toContain('# keep me');
+ expect(once).toContain('apiKeyEnv: ANTHROPIC_API_KEY');
+ expect(once).toContain('baseURL: http://localhost:3001/v1');
+ expect(once).not.toContain('http://old:1/v1');
+ expect(once).not.toContain('stale');
+ expect(once).toContain('provider: freellmapi');
+ expect(once).not.toContain('reasoningEffort');
+ expect(once).toContain('other: { a: 1 }');
+ expect(renderFile(file, once)).toBe(once);
+ });
+
+ it('renders structured YAML from an empty or comment-only document', () => {
+ const file = {
+ path: '/tmp/settings.yaml',
+ format: 'yaml' as const,
+ value: { a: { b: [1, 2] }, c: undefined },
+ };
+ expect(renderFile(file, '')).toBe('a:\n b:\n - 1\n - 2\n');
+ expect(renderFile(file, '# only a comment\n')).toContain('a:\n b:\n - 1\n - 2\n');
+ });
+
+ it('refuses to merge structured YAML into a document it cannot parse', () => {
+ const file = {
+ path: '/tmp/settings.yaml',
+ format: 'yaml' as const,
+ value: { a: 1 },
+ };
+ expect(() => renderFile(file, 'a: [1, 2\n')).toThrow(/cannot be parsed/);
+ expect(() => renderFile(file, '- just\n- a list\n')).toThrow(/not a mapping/);
+ });
+
it('replaces conflicting Codex TOML settings and retains unrelated tables', () => {
const existing = [
'# personal config',
diff --git a/cli/src/config-files.ts b/cli/src/config-files.ts
index 31d477a3..b73caf7e 100644
--- a/cli/src/config-files.ts
+++ b/cli/src/config-files.ts
@@ -6,6 +6,7 @@ import {
parse,
type ParseError,
} from 'jsonc-parser';
+import { Document, isMap, parseDocument } from 'yaml';
import type { GeneratedFile } from './types.js';
function isRecord(value: unknown): value is Record<string, unknown> {
@@ -54,6 +55,47 @@ function mergeJson(existing: string, value: Record<string, unknown>): string {
return rendered.endsWith('\n') ? rendered : `${rendered}\n`;
}
+// Structural YAML merge, the `mergeJson` rule applied to a YAML document:
+// nested objects recurse, everything else (scalars, arrays) is replaced at
+// that path, and an explicit `undefined` deletes the key (a generator's way
+// to retire a sibling the new value makes stale). Editing the parsed
+// Document rather than re-rendering from a plain object keeps the user's
+// comments, key order, and quoting for every node the patch does not touch —
+// a settings.yaml shared with other providers (DeepSeek Harness keeps every
+// route under one `llm-pi-ai` key) must not lose its siblings just because
+// ours changed.
+function mergeYamlDocument(existing: string, value: Record<string, unknown>): string {
+ if (!existing.trim()) {
+ const fresh = new Document(JSON.parse(JSON.stringify(value)));
+ return fresh.toString({ lineWidth: 0 });
+ }
+ const doc = parseDocument(existing);
+ if (doc.errors.length) {
+ throw new Error(`Existing YAML cannot be parsed safely: ${doc.errors[0].message}`);
+ }
+ if (doc.contents !== null && !isMap(doc.contents)) {
+ throw new Error('Existing YAML is not a mapping at the top level');
+ }
+ const applyPatch = (patch: Record<string, unknown>, parentPath: string[] = []) => {
+ for (const [key, next] of Object.entries(patch)) {
+ const propertyPath = [...parentPath, key];
+ if (next === undefined) {
+ doc.deleteIn(propertyPath);
+ continue;
+ }
+ const current = doc.getIn(propertyPath, true);
+ if (isRecord(next) && isMap(current)) {
+ applyPatch(next, propertyPath);
+ continue;
+ }
+ doc.setIn(propertyPath, next);
+ }
+ };
+ applyPatch(value);
+ const rendered = doc.toString({ lineWidth: 0 });
+ return rendered.endsWith('\n') ? rendered : `${rendered}\n`;
+}
+
function markerPattern(): RegExp {
return new RegExp(
`^[ \\t]*(?:#|//) freellmapi:start[\\s\\S]*?^[ \\t]*(?:#|//) freellmapi:end\\s*`,
@@ -258,7 +300,11 @@ function mergeEnv(existing: string, generated: string): string {
export function renderFile(file: GeneratedFile, existing = ''): string {
if (file.format === 'json') return mergeJson(existing, file.value ?? {});
if (file.format === 'env') return mergeEnv(existing, file.content ?? '');
- if (file.format === 'yaml') return mergeYaml(existing, file.content ?? '');
+ if (file.format === 'yaml') {
+ return file.value
+ ? mergeYamlDocument(existing, file.value)
+ : mergeYaml(existing, file.content ?? '');
+ }
return mergeToml(existing, file.content ?? '');
}
diff --git a/cli/src/tools.test.ts b/cli/src/tools.test.ts
index 8020ba26..9f68339b 100644
--- a/cli/src/tools.test.ts
+++ b/cli/src/tools.test.ts
@@ -213,6 +213,47 @@ describe('tool generators', () => {
}
});
+ it('declares a complete DeepSeek Harness route and claims the default model', () => {
+ const dsh = tools.find(tool => tool.id === 'dsh')!;
+ const generation = dsh.generate(context);
+ const [settings, env] = generation.files;
+ expect(settings.path).toBe('/home/tester/.dsh/settings.yaml');
+ expect(settings.format).toBe('yaml');
+ const value = settings.value as {
+ 'llm-pi-ai': { providers: Record<string, { api: string; baseURL: string; apiKeyEnv: string; models: { id: string }[] }> };
+ 'agent-default-model': { provider: string; model: string; reasoningEffort?: string };
+ };
+ const route = value['llm-pi-ai'].providers.freellmapi;
+ // A hand-declared route must carry api, baseURL, and a non-empty models
+ // list, or DSH refuses the whole section where it is written.
+ expect(route.api).toBe('openai-completions');
+ expect(route.baseURL).toBe('http://localhost:3000/v1');
+ expect(route.apiKeyEnv).toBe('FREELLMAPI_API_KEY');
+ expect(route.models.map(model => model.id)).toEqual(['fast-coder', 'reasoning-model']);
+ expect(value['agent-default-model']).toEqual({
+ provider: 'freellmapi',
+ model: 'fast-coder',
+ reasoningEffort: undefined,
+ });
+ expect('reasoningEffort' in value['agent-default-model']).toBe(true);
+ // DSH loads $DSH_HOME/.env as its user environment layer, which is how
+ // `apiKeyEnv` resolves without an export.
+ expect(env).toMatchObject({
+ path: '/home/tester/.dsh/.env',
+ format: 'env',
+ sensitive: true,
+ content: 'FREELLMAPI_API_KEY=freellmapi-test-key\n',
+ });
+ });
+
+ it('adds a named DeepSeek Harness profile as a second route without moving the default', () => {
+ const dsh = tools.find(tool => tool.id === 'dsh')!;
+ const value = dsh.generate({ ...context, profile: 'Work Laptop' }).files[0].value as Record<string, unknown>;
+ const providers = (value['llm-pi-ai'] as { providers: Record<string, unknown> }).providers;
+ expect(Object.keys(providers)).toEqual(['freellmapi-work-laptop']);
+ expect(value['agent-default-model']).toBeUndefined();
+ });
+
it('uses /v1 for every OpenAI-compatible generated base URL', () => {
for (const tool of tools.filter(entry => entry.protocol.startsWith('OpenAI'))) {
expect(tool.baseUrlSupport, tool.id).toBe('/v1');
diff --git a/cli/src/tools.ts b/cli/src/tools.ts
index 640bdb10..26d5ba9c 100644
--- a/cli/src/tools.ts
+++ b/cli/src/tools.ts
@@ -435,6 +435,83 @@ function crush(ctx: GenerateContext): Generation {
};
}
+// DeepSeek Harness (dsh) reads one YAML settings document, $DSH_HOME/settings.yaml
+// (default ~/.dsh). Every provider is a route under `llm-pi-ai.providers`;
+// a route pi-ai's installed catalog does not ship must spell out `api`,
+// `baseURL`, and a non-empty `models` list, which is exactly what a gateway
+// with a per-user live catalog is. The key travels through `apiKeyEnv`:
+// DSH loads $DSH_HOME/.env as its user environment layer, so writing the key
+// there (0600) makes the route work on the next request without an export.
+// No `compat` switches: the gateway already maps `developer` → `system` and
+// honours `max_completion_tokens`, the two things pi-ai sends to an endpoint
+// it cannot recognize.
+function dsh(ctx: GenerateContext): Generation {
+ const model = primaryModel(ctx.models, ctx.requestedModelId);
+ // DSH_HOME relocates the whole harness home; nothing else about the
+ // layout changes, so honour it the way dsh itself does.
+ const home = process.env.DSH_HOME?.trim() || path.join(ctx.homeDir, '.dsh');
+ // A route id is permanent in DSH (sessions, defaults, and credential refs
+ // name it) and must be lowercase; a named profile becomes a second route
+ // beside the default one rather than replacing it.
+ const route = ctx.profile === 'default'
+ ? 'freellmapi'
+ : `freellmapi-${ctx.profile.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')}`;
+ const roster = catalogModels(ctx.models);
+ const entries = [model, ...roster.filter(entry => entry.id !== model.id)]
+ .map(entry => ({
+ id: entry.id,
+ name: entry.name ?? entry.id,
+ contextWindow: contextWindow(entry),
+ maxTokens: outputLimit(entry),
+ }));
+ return {
+ files: [
+ {
+ path: path.join(home, 'settings.yaml'),
+ format: 'yaml',
+ value: {
+ 'llm-pi-ai': {
+ providers: {
+ [route]: {
+ displayName: ctx.profile === 'default' ? 'FreeLLMAPI' : `FreeLLMAPI (${ctx.profile})`,
+ apiKeyEnv: 'FREELLMAPI_API_KEY',
+ api: 'openai-completions',
+ baseURL: v1Url(ctx.url),
+ models: entries,
+ },
+ },
+ },
+ // The default model is only claimed for the default profile; a
+ // named route is an extra option in the picker, not a takeover.
+ // A previous default's `reasoningEffort` must go with it: DSH
+ // refuses a request naming a level the selected model cannot
+ // take, and a hand-declared model declares none.
+ ...(ctx.profile === 'default'
+ ? {
+ 'agent-default-model': {
+ provider: route,
+ model: model.id,
+ reasoningEffort: undefined,
+ },
+ }
+ : {}),
+ },
+ },
+ {
+ path: path.join(home, '.env'),
+ format: 'env',
+ sensitive: true,
+ content: `FREELLMAPI_API_KEY=${ctx.apiKey}\n`,
+ },
+ ],
+ notes: [
+ `Start DeepSeek Harness with: npx @deepseek-ai/dsh web — ${route}/${model.id} is ${ctx.profile === 'default' ? 'the default model' : 'in the model picker'}.`,
+ 'Settings are hot-reloaded, so a running dsh picks this up on its next request.',
+ `Models are declared text-only; give a vision model \`input: [text, image]\` under ${route}.models in settings.yaml to send it images.`,
+ ],
+ };
+}
+
function cursor(ctx: GenerateContext): Generation {
return {
files: [],
@@ -473,6 +550,7 @@ const metadata = [
['roo', 'Roo Code', 'code', 'file', 'OpenAI Chat', '/v1', 'setup-roo', 'https://docs.roocode.com', roo],
['kilo', 'Kilo Code', 'code', 'file', 'OpenAI Chat', '/v1', 'setup-kilo', 'https://kilocode.ai/docs', kilo],
['crush', 'Crush', 'code', 'file', 'OpenAI Chat', '/v1', 'setup-crush', 'https://github.com/charmbracelet/crush', crush],
+ ['dsh', 'DeepSeek Harness', 'agent', 'file', 'OpenAI Chat', '/v1', 'setup-dsh', 'https://github.com/deepseek-ai/deepseek-harness', dsh],
['cursor', 'Cursor', 'code', 'guide', 'OpenAI Chat', '/v1', 'setup-cursor', 'https://docs.cursor.com', cursor],
['generic', 'Generic OpenAI client', 'agent', 'guide', 'OpenAI Chat', '/v1', 'setup-generic', 'https://github.com/tashfeenahmed/freellmapi', generic],
] as const;
diff --git a/cli/src/types.ts b/cli/src/types.ts
index 77132c32..bd7ea0b0 100644
--- a/cli/src/types.ts
+++ b/cli/src/types.ts
@@ -9,7 +9,9 @@ export interface CatalogModel {
export interface GeneratedFile {
path: string;
format: 'json' | 'toml' | 'yaml' | 'env';
+ /** Structured patch, deep-merged into the existing document (json, yaml). */
value?: Record<string, unknown>;
+ /** Literal text, merged as a marked `# freellmapi:start/end` block (toml, yaml, env). */
content?: string;
sensitive?: boolean;
}
diff --git a/cli/tools.json b/cli/tools.json
index c035b0ec..12538900 100644
--- a/cli/tools.json
+++ b/cli/tools.json
@@ -10,6 +10,7 @@
{"id":"roo","name":"Roo Code","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-roo","docsUrl":"https://docs.roocode.com"},
{"id":"kilo","name":"Kilo Code","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-kilo","docsUrl":"https://kilocode.ai/docs"},
{"id":"crush","name":"Crush","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-crush","docsUrl":"https://github.com/charmbracelet/crush"},
+ {"id":"dsh","name":"DeepSeek Harness","category":"agent","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-dsh","docsUrl":"https://github.com/deepseek-ai/deepseek-harness"},
{"id":"cursor","name":"Cursor","category":"code","configType":"guide","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-cursor","docsUrl":"https://docs.cursor.com"},
{"id":"generic","name":"Generic OpenAI client","category":"agent","configType":"guide","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-generic","docsUrl":"https://github.com/tashfeenahmed/freellmapi"}
]
diff --git a/client/src/components/agent-icons.tsx b/client/src/components/agent-icons.tsx
index e3d0bc71..eaaec0a0 100644
--- a/client/src/components/agent-icons.tsx
+++ b/client/src/components/agent-icons.tsx
@@ -44,6 +44,8 @@ import { cn } from '@/lib/utils'
// cursor Cursor cursor.com/brand asset pack, `Cube/SVG/CUBE_2D_{LIGHT,DARK}.svg` Cursor TM, nominative use
// crush Crush no vector published; hue sampled from the official Charm TM, nominative use
// stuff.charm.sh/crush/charm-crush.png (Charm's `charple`)
+// dsh DeepSeek lettermark only: DSH's brand guidelines ask third parties not DeepSeek TM, nominative use
+// Harness to reuse official artwork; tinted with DeepSeek's brand blue
//
// id light tile ratio dark tile ratio dark-mode treatment
// claude #D37152 3.08 #D97757 5.52 brand #D97757 on dark; light tile is
@@ -70,6 +72,7 @@ import { cn } from '@/lib/utils'
// saturated yellow that clears 3:1 there
// cursor #26251E 14.10 #EDECEC 14.61 published pair (CUBE_2D_LIGHT/DARK)
// crush #6B50FF 4.57 #6B50FF 3.46 brand purple unchanged; clears on both tiles
+// dsh #4D6BFE 3.97 #4D6BFE 3.98 brand blue unchanged; clears on both tiles
// generic currentColor — currentColor — not a brand mark
//
// Cursor also publishes a 2.5D cube in five warm greys (#43413c #55544f #72716d
@@ -205,6 +208,11 @@ const brands: Record<string, Brand> = {
crush: {
tint: '[--mk:#6B50FF] dark:[--mk:#6B50FF]',
},
+ // DeepSeek Harness asks third parties not to reuse its official artwork
+ // (BRAND_GUIDELINES.md), so the lettermark stands in, in DeepSeek's blue.
+ dsh: {
+ tint: '[--mk:#4D6BFE] dark:[--mk:#4D6BFE]',
+ },
// Any other OpenAI-compatible client: our own terminal glyph, not a brand
// mark, so it keeps the page foreground colour on both tiles.
generic: {
diff --git a/client/src/data/agent-tools.json b/client/src/data/agent-tools.json
index c035b0ec..12538900 100644
--- a/client/src/data/agent-tools.json
+++ b/client/src/data/agent-tools.json
@@ -10,6 +10,7 @@
{"id":"roo","name":"Roo Code","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-roo","docsUrl":"https://docs.roocode.com"},
{"id":"kilo","name":"Kilo Code","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-kilo","docsUrl":"https://kilocode.ai/docs"},
{"id":"crush","name":"Crush","category":"code","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-crush","docsUrl":"https://github.com/charmbracelet/crush"},
+ {"id":"dsh","name":"DeepSeek Harness","category":"agent","configType":"file","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-dsh","docsUrl":"https://github.com/deepseek-ai/deepseek-harness"},
{"id":"cursor","name":"Cursor","category":"code","configType":"guide","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-cursor","docsUrl":"https://docs.cursor.com"},
{"id":"generic","name":"Generic OpenAI client","category":"agent","configType":"guide","protocol":"OpenAI Chat","baseUrlSupport":"/v1","command":"setup-generic","docsUrl":"https://github.com/tashfeenahmed/freellmapi"}
]
diff --git a/client/src/pages/AgentsPage.tsx b/client/src/pages/AgentsPage.tsx
index 34384d93..f4b6de0f 100644
--- a/client/src/pages/AgentsPage.tsx
+++ b/client/src/pages/AgentsPage.tsx
@@ -40,6 +40,7 @@ const analyticsIds: Record<string, string> = {
roo: 'roo',
kilo: 'kilo-code',
crush: 'crush',
+ dsh: 'deepseek-harness',
cursor: 'cursor',
}
diff --git a/docs/clients.md b/docs/clients.md
index 52a32940..51bc447d 100644
--- a/docs/clients.md
+++ b/docs/clients.md
@@ -48,13 +48,39 @@ context windows.
| **Roo Code** | `setup-roo` | `http://localhost:3001/v1` | OpenAI Chat |
| **Kilo Code** | `setup-kilo` | `http://localhost:3001/v1` | OpenAI Chat |
| **Crush** | `setup-crush` | `http://localhost:3001/v1` | OpenAI Chat |
+| **DeepSeek Harness** | `setup-dsh` | `http://localhost:3001/v1` | OpenAI Chat (`api: openai-completions`) |
| **Cursor** | `setup-cursor` prints the guide | public `https://…/v1` | OpenAI Chat |
| **Anything else** | `setup-generic` prints a ready block | `http://localhost:3001/v1` | OpenAI Chat |
The root-vs-`/v1` distinction matters: Claude Code expects the server root
because it appends the Anthropic Messages path. OpenAI-compatible clients in
this table—including Cline, Aider, Goose, Codex, Continue, OpenCode, Qwen,
-Roo, Kilo, and Crush—expect their configured base URL to include `/v1`.
+Roo, Kilo, Crush, and DeepSeek Harness—expect their configured base URL to
+include `/v1`.
+
+### DeepSeek Harness (`dsh`)
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) keeps
+every provider as a route under `llm-pi-ai.providers` in
+`$DSH_HOME/settings.yaml` (`~/.dsh` by default). `setup-dsh` adds a
+`freellmapi` route there — `api: openai-completions`, the gateway's `/v1`
+base URL, and the live catalog as the route's `models` list, which DSH
+requires for a provider its installed catalog does not ship — and makes
+`freellmapi/auto` the default model. The key goes into `$DSH_HOME/.env`
+(mode 0600) as `FREELLMAPI_API_KEY`, the environment layer DSH reads on its
+own, so nothing needs exporting. Both writes are structural merges: other
+routes, comments, and settings in the file are left as they were.
+
+```bash
+npx freellmapi setup-dsh --url http://localhost:3001 --api-key <unified-key>
+npx @deepseek-ai/dsh web
+```
+
+Settings are hot-reloaded, so a running `dsh` uses the route on its next
+request. `--profile <name>` adds a second route (`freellmapi-<name>`) without
+changing the default model; `--model <id>` pins the default. Routes are
+declared text-only — add `input: [text, image]` to a model entry under
+`freellmapi.models` to send it images. `DSH_HOME` is honoured when set.
## Native Gemini clients
diff --git a/package-lock.json b/package-lock.json
index 30c07c99..ec0bdb17 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -25,7 +25,8 @@
"version": "0.4.0",
"license": "MIT",
"dependencies": {
- "jsonc-parser": "^3.3.1"
+ "jsonc-parser": "^3.3.1",
+ "yaml": "^2.9.0"
},
"bin": {
"freellmapi": "dist/index.js"
@@ -12593,6 +12594,21 @@
"integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
"license": "ISC"
},
+ "node_modules/yaml": {
+ "version": "2.9.0",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
+ },
"node_modules/yargs": {
"version": "17.7.2",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
diff --git a/repo-assets/agents/deepseek-harness.png b/repo-assets/agents/deepseek-harness.png
new file mode 100644
index 00000000..96b301df
Binary files /dev/null and b/repo-assets/agents/deepseek-harness.png differ
diff --git a/server/src/__tests__/lib/client-classifier.test.ts b/server/src/__tests__/lib/client-classifier.test.ts
index 5180d4fd..eb81ac9b 100644
--- a/server/src/__tests__/lib/client-classifier.test.ts
+++ b/server/src/__tests__/lib/client-classifier.test.ts
@@ -34,6 +34,9 @@ describe('client agent classification', () => {
expect(classifyClientAgent(request('/v1/chat/completions', {
'user-agent': 'crush/0.8',
}))).toBe('crush');
+ expect(classifyClientAgent(request('/v1/chat/completions', {
+ 'user-agent': 'deepseek-harness/0.3.1 (+https://github.com/deepseek-ai/deepseek-harness)',
+ }))).toBe('deepseek-harness');
});
it('recognizes Claude Code by its real claude-cli user agent', () => {
diff --git a/server/src/lib/client-classifier.ts b/server/src/lib/client-classifier.ts
index 6f599845..0d1f6efc 100644
--- a/server/src/lib/client-classifier.ts
+++ b/server/src/lib/client-classifier.ts
@@ -12,6 +12,7 @@ export const CLIENT_AGENTS = [
'qwen-code',
'kilo-code',
'crush',
+ 'deepseek-harness',
'cursor',
'gemini-cli',
'zed',
@@ -52,6 +53,8 @@ export function classifyClientAgent(req: Request): ClientAgent {
if (/gemini[- /]?cli/.test(ua)) return 'gemini-cli';
if (/kilo[- ]?code|\bkilocode\b/.test(ua)) return 'kilo-code';
if (/\bcrush(?:\/|\s|$)/.test(ua)) return 'crush';
+ // `deepseek-harness/<version> (+https://github.com/deepseek-ai/deepseek-harness)`
+ if (/deepseek[- ]?harness|\bdsh\//.test(ua)) return 'deepseek-harness';
if (/opencode/.test(ua)) return 'opencode';
if (/\bcline\b/.test(ua)) return 'cline';
if (/\broo[- /]/.test(ua) || /roo code/.test(ua)) return 'roo';