Tutorial: Offline Agentic coding with llama-server

[rujialiu]

Motivation

There are excellent commercial LLMs for agentic coding. However, using llama-server is still a very attractive option because maybe:

• You want a 100% offline environment (e.g. to make sure no private data is sent through network).
• You already run out of budget
• You want to do some unpredictable experiments (like using openevolve to discover new algorithms/optimize some critical code) that you have no idea how many tokens you will need, and don't want to risk.

LLM

My personal favorite one is Devstral-Small-2507, which works great in real-world scenario (not just optimized for benchmarks or small programming problems). Key information

• 24B parameters
• 128k context
• Q4_K_M can fit completely in a 24GB-VRAM GPU with 128k context with 4-bit kv cache.
• Q2_K_L can fit completely in a 12GB-VRAM GPU with -nkvo

So if you have a 24GB GPU like 4090 and don't need concurrent access, start server like this:

llama-server.exe -a Devstral-Small-2507 -m Devstral-Small-2507-Q4_K_M.gguf -c 131072 -fa -ngl 99 -ctk q4_0 -ctv q4_0 --jinja

If you have 12GB a GPU like 3070 Super like me, the best combination I found, is to keep kv cache in RAM (with -nkvo) and use Q2_K_L. At first, I was hesitate to use such a low bit quantization and 4-bit kv quantization, but the result is surprisingly good (compared to my expectiation):

llama-server.exe -a Devstral-Small-2507 -m mistralai_Devstral-Small-2507-Q2_K_L.gguf -c 524288 -fa -ngl 99 -ctk q4_0 -ctv q4_0 -nkvo -np 4 --jinja

Note that since I already kept kv cache in RAM, and I have 64GB RAM, I use -np 4 to allow 4 concurrent access, each having 128k context (thus -c 524288 in total). This setup uses ~24GB RAM (but a little bit >32GB peak RAM).

If you have a less powerful GPU / less RAM, just reduce some of the numbers above. For example, if you have a 6GB GPU, you can use -ngl 20 (there are 41 layers in total), then llama-server will only use ~5.2GB VRAM at startup. If you have 8GB GPU, -ngl 30 (~7.2GB) might be good.

The used VRAM will slowly increase (like 0.2GB per hour), but it doesn't really matter a lot because you can just restart the server and most agentic softwares will retry and continue to work.

Bottom line: you can even use pure CPU inference to get some "background jobs" done. It's slow, but acceptable.

If you prefer smaller LLMs, you can check the following (but I don't have much experience):

• DeepSeek-R1-0528-Qwen3-8B
• Seed-Coder-8B-Instruct (warning: only 32k context)
• DeepCoder-14B-Preview

It's also possible to use general-purpose LLMs like Qwen3, but even Qwen3-30B-A3B seems not good enough to me (with or without thinking).

Also, you can try to reduce context size, but it looks like it's quite easy to have 80k~100k tokens in context. You might be able to get it working with 64k by clearing/compacting context frequently, but 32k seems to be too small.

Software

There are already a couple of agentic coding softwares that supports OpenAI-compatible servers, so you can use llama-server with them without much effort:

• Cline
• Roo Code
• Aider
• OpenHands
• goose

With claude-code-router you can actually use llama-server served LLM in Claude Code!

For gemini-cli, it's still not clear whehther it'll support custom LLMs eventually (there are a few PRs not merged), but if you want to try today, you can check a fork with multi-provider support LLxprt Code

Usually, if you only use cline or similar softwares on your own machine, you don't need concurrent access; but if you use Claude Code, it will sometimes spawn multiple agents and make concurrent access.

Example: Using llama-server in Claude Code

Install (Current Claude Code version: 1.0.51):

npm install -g @anthropic-ai/claude-code
npm install -g @musistudio/claude-code-router

You only need to configure claude-code-router, with ~/.claude-code-router/config.json. You can find detailed description of settings in its documentation, but here is a minimal working example (attention: logs are huge! you may want to turn it off once you're happy with the settings):

{
  "LOG":true,
  "Providers": [
    {
        "name": "llamacpp",
        "api_base_url": "http://127.0.0.1:8080/v1/chat/completions",
        "api_key": "llamacpp",
        "models": ["Devstral-Small-2507"]
    }
  ],
  "Router": {
    "default": "llamacpp,Devstral-Small-2507",
    "background": "llamacpp,Devstral-Small-2507",
    "think": "llamacpp,Devstral-Small-2507",
    "longContext": "llamacpp,Devstral-Small-2507"
  }
}

Then use ccr code to launch claude-code-router along with Claude Code. Ask it to do something like "write a pacman game with pygame. Plan first, then write code." You will quickly get error messages in red if your setup doesn't work. For example, if you forgot the --jinja switch, you'll be told that your LLM doesn't support tool calling.

If everything goes on well, you'll see Claude Code wrote a TODO list, write some code, execute it, fixes bugs and update the TODO etc, with a lot of log messages from llama-server. Isn't that exciting? :)

PS: I'll update this tutorial when I have experience with more LLMs and softwares. Feedbacks and discussions are welcome!

[rujialiu]

Thanks @ggerganov for inviting me to write this!

[ggerganov]

Thanks for the write up - this is quite interesting I have to say.

It's also possible to use general-purpose LLMs like Qwen3, but even Qwen3-30B-A3B seems not good enough to me (with or without thinking).

Strange - I tried it exactly with Qwen3-30B-A3B with thinking and it did a good job writing a python script that I needed. I will test with some other models and report back.

To improve the tutorial, we should add a few sample setups for different machines. I'll provide a few commands that would work on Macs.

One thing to note is that the llama-server is very well suited for this use case because the Claude Code seems to send some small requests in between the long running context, which if you don't enable the -np option, will destroy your prefix caching. With -np 4 for example, each of these tiny requests gets assigned to a separate context slot and this way the big context remains intact and ready for reuse when the agent continues.

Do you know is it possible to add custom tools to this setup?

---

Will play with this for a few days and help you improve the tutorial. We should share it around when it is ready.

[rujialiu]

Strange - I tried it exactly with Qwen3-30B-A3B with thinking and it did a good job writing a python script that I needed. I will test with some other models and report back.

Oh yes, Qwen3-30B-A3B can write useful python scripts and I used it for a while too. I used to think it's good enough, until I used Devstral-Small-2507 😄

If I remember correctly, it either:

• thinks too much, writing a lot of code in "think" tag and then again outside it, effectively doubling the token usage.
• missed a lot of details after disabled thinking. For example, if you ask it to write a tetris game in cline, it probably doesn't even handle keyboard event, or the tetris blocks don't fall.

And it's also less powerful when I ask it to write some non-trivial algorithm in C++, convert serial C++ code to parallel using TBB etc. Devstral-Small-2507 also makes mistakes and sometimes behave strangely (maybe because of Q2_K_L and 4-bit kv cache) but overall I find it much more usable than Qwen3-30B-A3B when doing more advanced tasks.

To improve the tutorial, we should add a few sample setups for different machines. I'll provide a few commands that would work on Macs.
Thanks!

Do you know is it possible to add custom tools to this setup?
Yes, it supports both local and remote MCP servers. Do you think I should add relavant information in this tutorial?

Will play with this for a few days and help you improve the tutorial. We should share it around when it is ready.
Great! Thanks 😄

[am17an]

Pretty cool! I was looking for something like this. I also think there is need for an open source equivalent of Claude code we can iterate on with llama server

[am17an]

Probably time for llama.cpp community to build a MIT licensed alternative!

[rmatif]

There is also opencode, which is basically the same as Claude Code but open-source, MIT-licensed, and appears to be under active development

[rujialiu]

I actually stared opencode but it lacks Windows support so I didn't try. But on other platform it's definitel worth trying.

[rmatif]

They have a pre-built Windows binary in their releases section

[rujialiu]

Oh, I didn't notice that. I just saw sst/opencode#631 is still open :)

[rujialiu]

Just for discussion: currently I don't have any VLM to recommend. I don't normally write front-end codes but for some in-house tools, it's really handy to convert a screenshot to html/css. Currently the best open source LLM for this is probably https://github.com/THUDM/GLM-4.1V-Thinking but it's not supported by llama.cpp yet. The best supported VLM is probably Qwen2.5VL and InternVL3, but they're far behind GLM-4.1V-Thinking when doing Design2Code-like tasks.

[rujialiu]

I've just tried https://github.com/acoliver/llxprt-code/

Install:

npm install -g @vybestack/llxprt-code

Run:

llxprt

Then in llxprt, type:

/provider openai
/baseurl http://localhost:8080/v1/
/model

And manually select the model from the list. That's all. I tried "Write a full-featured pacman game in python with pygame. Write specs to files, and write code according to the specs."

Seems to have much better windows support than OpenHands and Claude Code (I'm getting path issues and invalid "bash command" issues in both). UI is extremely similar, but some details are better than Claude Code. Console output is also much more helpful (I suspect it's also due to better Windows support).

Very good first impression!

[rujialiu]

Biggest disapointment: llxprt-code and gemini-cli doesn't support Claude Code's custom slash command. We only have GEMINI.md (and LLXPRT.md in case of llxprt). Luckily, there is a tracking issue on it google-gemini/gemini-cli#3789

[engrtipusultan]

Can you tell me how do you pass system prompt in llama.cpp server?

[engrtipusultan]

Yes thank you. there is a knob for manually giving jinja template. There is no knob for system prompt in server. I believe there is one for llama.cpp cli.
Do you know link to documentation about writing valid jinja template?

[rujialiu]

I think system prompt should be sent by the client, because it's very application-dependent (and different agent in the same app often use different system prompt). I never tried to write my own jinja template for an LLM but if you want to adapt an existing one, try to understand that existing template should be enough (along with official jinja project docs) @engrtipusultan

[engrtipusultan]

Conversation: valid input to the model is a conversation, which consists of a list of messages. Each message contains the following fields.

role (required): specifies the source of each message. As described in [Instructions and levels of authority](https://model-spec.openai.com/2025-02-12.html#levels_of_authority) and [The chain of command](https://model-spec.openai.com/2025-02-12.html#chain_of_command), roles determine the authority of instructions in the case of conflicts.
    system: messages added by OpenAI
    developer: from the application developer (possibly also OpenAI)
    user: input from end users, or a catch-all for data we want to provide to the model
    assistant: sampled from the language model
    tool: generated by some program, such as code execution or an API call

This is from openai. From this I inferred that system prompt is the one that you set while setting up the server. This is something client request cannot override.
(official jinja project docs) what do you mean by that? documentation for jinja or jinja acceptable by lama.cpp. Initially I looked at ollama and it does not accept all kinds of jinja template. If there is documentation on jinja acceptable by llama.cpp kindly point me towards it.

[rujialiu]

This is from openai. From this I inferred that system prompt is the one that you set while setting up the server. This is something client request cannot override.

The document was true long ago, but now it's misleading.

Let me explain it in detail. You already know that may models come with built-in jinja template. But what's exactly inside? Let's take a look. For example, devstral-small's chat template begins with:

{%- set default_system_message = 'You are Devstral, a helpful agentic model trained by Mistral AI and using the OpenHands scaffold. You can interact with a computer to solve tasks.\\n\\n<ROLE>\\nYour primary role is to assist users by executing commands, modifying code, and solving technical problems effectively. You should be thorough, methodical, and prioritize quality over speed.\\n* If the user asks a question, like \\"why is X happening\\", don\'t try to fix the problem. Just give an answer to the question.\\n</ROLE>\\n\\n<EFFICIENCY>\\n* Each action you take is somewhat expensive. Wherever possible, combine multiple actions into a single action, e.g. combine multiple bash commands into one, using sed and grep to edit/view multiple files at once.\\n* When exploring the codebase, use efficient tools like find, grep, and git commands with appropriate filters to minimize unnecessary operations.\\n</EFFICIENCY>\\n\\n<FILE_SYSTEM_GUIDELINES>\\n* When a user provides a file path, do NOT assume it\'s relative to the current working directory. First explore the file system to locate the file before working on it.\\n* If asked to edit a file, edit the file directly, rather than creating a new file with a different filename.\\n* For global search-and-replace operations, consider using `sed` instead of opening file editors multiple times.\\n</FILE_SYSTEM_GUIDELINES>\\n\\n<CODE_QUALITY>\\n* Write clean, efficient code with minimal comments. Avoid redundancy in comments: Do not repeat information that can be easily inferred from the code itself.\\n* When implementing solutions, focus on making the minimal changes needed to solve the problem.\\n* Before implementing any changes, first thoroughly understand the codebase through exploration.\\n* If you are adding a lot of code to a function or file, consider splitting the function or file into smaller pieces when appropriate.\\n</CODE_QUALITY>\\n\\n<VERSION_CONTROL>\\n* When configuring git credentials, use \\"openhands\\" as the user.name and \\"[email protected]\\" as the user.email by default, unless explicitly instructed otherwise.\\n* Exercise caution with git operations. Do NOT make potentially dangerous changes (e.g., pushing to main, deleting repositories) unless explicitly asked to do so.\\n* When committing changes, use `git status` to see all modified files, and stage all files necessary for the commit. Use `git commit -a` whenever possible.\\n* Do NOT commit files that typically shouldn\'t go into version control (e.g., node_modules/, .env files, build directories, cache files, large binaries) unless explicitly instructed by the user.\\n* If unsure about committing certain files, check for the presence of .gitignore files or ask the user for clarification.\\n</VERSION_CONTROL>\\n\\n<PULL_REQUESTS>\\n* When creating pull requests, create only ONE per session/issue unless explicitly instructed otherwise.\\n* When working with an existing PR, update it with new commits rather than creating additional PRs for the same issue.\\n* When updating a PR, preserve the original PR title and purpose, updating description only when necessary.\\n</PULL_REQUESTS>\\n\\n<PROBLEM_SOLVING_WORKFLOW>\\n1. EXPLORATION: Thoroughly explore relevant files and understand the context before proposing solutions\\n2. ANALYSIS: Consider multiple approaches and select the most promising one\\n3. TESTING:\\n   * For bug fixes: Create tests to verify issues before implementing fixes\\n   * For new features: Consider test-driven development when appropriate\\n   * If the repository lacks testing infrastructure and implementing tests would require extensive setup, consult with the user before investing time in building testing infrastructure\\n   * If the environment is not set up to run tests, consult with the user first before investing time to install all dependencies\\n4. IMPLEMENTATION: Make focused, minimal changes to address the problem\\n5. VERIFICATION: If the environment is set up to run tests, test your implementation thoroughly, including edge cases. If the environment is not set up to run tests, consult with the user first before investing time to run tests.\\n</PROBLEM_SOLVING_WORKFLOW>\\n\\n<SECURITY>\\n* Only use GITHUB_TOKEN and other credentials in ways the user has explicitly requested and would expect.\\n* Use APIs to work with GitHub or other platforms, unless the user asks otherwise or your task requires browsing.\\n</SECURITY>\\n\\n<ENVIRONMENT_SETUP>\\n* When user asks you to run an application, don\'t stop if the application is not installed. Instead, please install the application and run the command again.\\n* If you encounter missing dependencies:\\n  1. First, look around in the repository for existing dependency files (requirements.txt, pyproject.toml, package.json, Gemfile, etc.)\\n  2. If dependency files exist, use them to install all dependencies at once (e.g., `pip install -r requirements.txt`, `npm install`, etc.)\\n  3. Only install individual packages directly if no dependency files are found or if only specific packages are needed\\n* Similarly, if you encounter missing dependencies for essential tools requested by the user, install them when possible.\\n</ENVIRONMENT_SETUP>\\n\\n<TROUBLESHOOTING>\\n* If you\'ve made repeated attempts to solve a problem but tests still fail or the user reports it\'s still broken:\\n  1. Step back and reflect on 5-7 different possible sources of the problem\\n  2. Assess the likelihood of each possible cause\\n  3. Methodically address the most likely causes, starting with the highest probability\\n  4. Document your reasoning process\\n* When you run into any major issue while executing a plan from the user, please don\'t try to directly work around it. Instead, propose a new plan and confirm with the user before proceeding.\\n</TROUBLESHOOTING>\\n' %}
{{- bos_token }}
{%- if messages[0]['role'] == 'system' %}
    {%- if messages[0]['content'] is string %}
        {%- set system_message = messages[0]['content'] %}
    {%- else %}
        {%- set system_message = messages[0]['content'][0]['text'] %}
    {%- endif %}
    {%- set loop_messages = messages[1:] %}
{%- else %}
    {%- set system_message = default_system_message %}
    {%- set loop_messages = messages %}
{%- endif %}
    {{- '[SYSTEM_PROMPT]' + system_message + '[/SYSTEM_PROMPT]' }}

You can see that:

• it defines a default_system_message within the template
• client can override system message with a message whose role is system (the if messages[0]['role'] == 'system' part)

For a real example of how a complex client system message can be built, here is how agno (a popular agent framework) does it:

https://github.com/agno-agi/agno/blob/554a8d31972289888554c83d6cf697c208f43bde/libs/agno/agno/agent/agent.py#L4348

(official jinja project docs) what do you mean by that? documentation for jinja or jinja acceptable by lama.cpp.

Jinja is a popular python templating engine that existed long before LLM. People (including me) used Jinja to generate html files etc.
I don't think you need to learn "jinja acceptable by lama.cpp". Just look carefully into the template like I show you above and reason about it. That should be enough.

[engrtipusultan]

Thank you

[am17an]

@rujialiu I was following your tutorial, namely using claude code router + llama server with Devstral-Small-2507-Q4_K_M.gguf, I might've misconfigured something but when I ask it a simple question like "explain the speculative example in this repo" inside llama.cpp, it will do something like

● Search(pattern: "*speculative*", path: "examples")
  ⎿  Found 0 files

● {
    "tool_calls": [
      {
        "name": "Glob",
        "arguments": {
          "pattern": "speculative"
        }
      }
    ]
  }

But it won't actually make the tool call and just stop at this point. Did you face this issue?

[rujialiu]

On the other hand, llxprt is much faster and gives the following ansewr @am17an :

╭──────────────────────────────────────────────────╮
│  > explain the speculative example in this repo  │
╰──────────────────────────────────────────────────╯

 ╭───────────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ✔  FindFiles '**/speculative*' within .                                                           │
 │                                                                                                   │
 │    Found 4 matching file(s)                                                                       │
 ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─────────────────────────────────────────────╮
 │ ✔  ReadFile examples\speculative\README.md  │
 ╰─────────────────────────────────────────────╯
 ╭──────────────────────────────────────────────────────╮
 │ ✔  ReadFile ...examples\speculative\speculative.cpp  │
 ╰──────────────────────────────────────────────────────╯
 ╭───────────────────────────────────────────────╮
 │ ✔  ReadFile examples\\speculative-simple.cpp  │
 ╰───────────────────────────────────────────────╯
✦ The speculative decoding example in this repository demonstrates speculative decoding techniques for large
  language models (LLMs). There are two main examples:

   1. speculative.cpp (in examples/speculative/): This example shows speculative decoding using two models: a
      target model (the main model) and a draft model (a smaller, faster model). The draft model generates
      candidate tokens, and the target model verifies and accepts these tokens. This can improve generation
      speed by allowing the draft model to propose tokens while the target model evaluates them.

   2. speculative-simple.cpp (in examples/speculative-simple/): A simplified version that focuses on
      speculative decoding using a single model but with a separate context for drafting tokens. It
      demonstrates the core idea of generating draft tokens and evaluating them with the main model.

  Both examples aim to speed up token generation by speculative generation and verification, leveraging the
  trade-off between accuracy and speed. The key idea is to use a draft model (or draft context) to propose
  tokens, which the target model then verifies, accepting the most probable ones.

  For more details, you can refer to the linked GitHub pull requests in the README.md file:
   - https://github.com/ggml-org/llama.cpp/pull/2926
   - https://github.com/ggml-org/llama.cpp/pull/3624
   - https://github.com/ggml-org/llama.cpp/pull/5625

[rujialiu]

I changed kv cache to Q8_0 from Q4_0 following your suggestion and observed some improvements when doing multi-file tasks (but no scientific numbers). But due to lack of RAM, I had to reduce -np 4 to -np 2. Will use this setup some more time. And since you have a mac with lot of memory, maybe DeepSeek-R1-0528 and/or its R1T2 variant is worth trying out. Also, I've heard that R2 is coming. @ggerganov

[rujialiu]

Today I've upgrade CC to 1.0.56. The windows support is greatly enhanced so no more path-related issues are obesrved. I don't know whether you're using windows, too, but you can try to upgrade and see whether we're still having trouble with Glob tool @am17an

[ggerganov]

And since you have a mac with lot of memory, maybe DeepSeek-R1-0528 and/or its R1T2 variant is worth trying out.

I don't think such big models make sense for local use at the context sizes needed here. I'm interested in more lightweight solutions that are practical.

[rujialiu]

I don't think such big models make sense for local use at the context sizes needed here. I'm interested in more lightweight solutions that are practical.

Ok, I understand. It's not practical for daily use yes, but I'm doing this in my office PC sometimes, let it write the initial version of some complex code for the whole night, then iterate on that (with lightweight models) when I'm back the next morning. Sometimes it works great (higher quality than lightweight model's output), sometimes it's too slow to finish its work before I come back. It's still an interesting use case I think.

[rujialiu]

I've just tried opencode v0.3.46 (thanks to @rmatif for telling me windows is already supported). While it frequently crashed (OOM?) with somewhat large projects (maybe not because of code size, but other big binary files that it should actually ignore), it works well with smaller projects.

Just download the binary, make sure ripgrep is on path (otherwise opencode will download it from github) and write an opencode.json in your project directory:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llamacpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama.cpp (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "Devstral-Small-2507": {
          "name": "Devstral-Small-2507 (local)"
        }
      }
    }
  },
  "model": "llamacpp/Devstral-Small-2507"
}

I just tried OpenHands's repo, tell it to "summarize this repo", but I'm surprised that it changed README.md without asking me. But anyway, I will spend some more time and try to make best use of it.

BTW: I like its C/S design and TUI written in go.

[rujialiu]

Ok, I think it changed README.md because by default it's in BUILD mode. I switched to PLAN mode and it doesn't change anything now. However, it did Fetch https://github.com/sst/opencode (format=markdown) but the repository is OpenHands. Strange.

[rujialiu]

I'm been experimenting with Kimi-K2 and Qwen3-Coder for a few days, both quite good: K2 is better at enginnering and Qwen3-Coder seems to be a little bit better at producing complex but one-off scripts.

Since Qwen3-Coder's blog said "more sizes are coming", there's a good chance there will be some model similar in size to 30B-A3B, perfect for local use, and also some tiny models that can be used as draft models, so maybe we can experiment with speculative decoding after they're published?

I've heard that EAGLE-3 is worth trying (and supported by vllm and sglang), but I don't know which speculative decoding algorithm llama.cpp implements, and whether EAGLE-3 is planned or not. @ggerganov