# poolside/Laguna-M.1 — vLLM serving recipe

> Poolside's 225B total / 23B activated MoE coding model with global attention, native interleaved reasoning, and 256K context — designed for agentic coding and long-horizon work.

Configuration: hardware `h200` (8× H200) · strategy `single_node_tp` (Tensor Parallel) · variant `default` (BF16) · features `tool_calling`, `reasoning`

- Interactive page: https://vllm-recipes-git-preview-vllm-pr-60762-inferact-inc.vercel.app/poolside/Laguna-M.1
- This configuration as JSON: https://vllm-recipes-git-preview-vllm-pr-60762-inferact-inc.vercel.app/poolside/Laguna-M.1.json?hardware=h200

The commands below were rendered for exactly this configuration and take precedence over any example in the guide.

## Other configurations

Change the query string (the same parameters as the page URL) and fetch this URL again. Unknown or incompatible values fall back to the recipe default, so check the Configuration line.

- `hardware`: `h100`, `h200`, `b200`, `gb200`, `b300`, `gb300`, `mi300x`, `mi325x`, `mi350x`, `mi355x`
- `variant`: `default`, `fp8`, `nvfp4`
- `strategy`: `single_node_tp`, `single_node_tep`, `single_node_dep`, `multi_node_tp`, `multi_node_dep`, `multi_node_tep` (multi-node strategies also need `nodes=<n>`)
- `features`: comma-separated list of `tool_calling`, `reasoning` (default: `tool_calling`, `reasoning`)

## Install

Requires vLLM >= 0.21.0.

```bash
uv venv
source .venv/bin/activate
uv pip install -U vllm --torch-backend auto
```

Docker image: `vllm/vllm-openai:latest`

## Serve

```bash
vllm serve poolside/Laguna-M.1 \
  --tensor-parallel-size 8 \
  --enable-auto-tool-choice \
  --tool-call-parser poolside_v1 \
  --reasoning-parser poolside_v1 \
  --default-chat-template-kwargs '{"enable_thinking": true}'
```

Docker equivalent:

```bash
docker run --gpus all \
  --privileged --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest poolside/Laguna-M.1 \
  --tensor-parallel-size 8 \
  --enable-auto-tool-choice \
  --tool-call-parser poolside_v1 \
  --reasoning-parser poolside_v1 \
  --default-chat-template-kwargs '{"enable_thinking": true}'
```

## Guide

> Background reference. Commands in it are examples and may target another configuration — use the Serve section above.

### Overview

[Laguna M.1](https://huggingface.co/poolside/Laguna-M.1) is Poolside's 225B-total / 23B-activated Mixture-of-Experts model purpose-built for agentic coding and long-horizon work. It is competitive with state-of-the-art open-weight and frontier models on SWE-bench Verified (74.6%), SWE-bench Multilingual, SWE-Bench Pro, and Terminal-Bench 2.0.

#### Key features
- **Large sparse MoE**: 70-layer transformer — the first 3 layers are dense SwiGLU, the remaining 67 are sparse MoE with **256 experts + 1 shared expert** and top-k=16 routing with auxiliary-loss-free load balancing.
- **Global attention**: global attention across all layers with 64 Q-heads, 8 KV-heads, head dim 128, and softplus attention output gating.
- **256K context**: RoPE with YaRN extends the context window to 262,144 tokens.
- **Native interleaved reasoning**: thinking blocks emitted before and between tool calls, with *preserved thinking* (returning prior `reasoning` in history) recommended for best agentic performance. Toggled per-request via `enable_thinking`.
- **Tool calling**: Poolside-specific tool-call protocol, parsed via `poolside_v1`.

### Prerequisites

Laguna M.1 support landed in vLLM via [PR #41129](https://github.com/vllm-project/vllm/pull/41129) (shared implementation with [Laguna XS.2](https://huggingface.co/poolside/Laguna-XS.2)) and ships in **vLLM 0.21.0 and later**.

```bash
uv pip install -U 'vllm>=0.21.0'
```

FP8 and NVFP4 quantized checkpoints are available at [Laguna-M.1-FP8](https://huggingface.co/poolside/Laguna-M.1-FP8) and [Laguna-M.1-NVFP4](https://huggingface.co/poolside/Laguna-M.1-NVFP4). Quantization is detected automatically from the checkpoint's `quantization_config`, so the launch command is identical — just swap the model ID (select the variant above).

### Launch command

#### Single node (8×H200, BF16)
```bash
vllm serve poolside/Laguna-M.1 \
  --tensor-parallel-size 8 \
  --served-model-name laguna \
  --enable-auto-tool-choice \
  --tool-call-parser poolside_v1 \
  --reasoning-parser poolside_v1 \
  --default-chat-template-kwargs '{"enable_thinking": true}'
```

The BF16 checkpoint (~450 GB of weights) fits on a single 8×H200 node. Use the **FP8** variant to run on 4 GPUs, or the **NVFP4** variant (Blackwell only) to fit within ~135 GB.

### Controlling reasoning

Reasoning is enabled at the server when you pass `--default-chat-template-kwargs '{"enable_thinking": true}'` (included above). Poolside recommends **preserved thinking** for agentic coding — return the previous assistant turn's `reasoning` in the message history.

```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

resp = client.chat.completions.create(
    model="laguna",
    messages=[{"role": "user", "content": "Write a Python retry wrapper with exponential backoff."}],
    temperature=1.0,
    extra_query={"top_k": 20},
    stream=True,
)
for chunk in resp:
    delta = chunk.choices[0].delta
    rc = delta.reasoning
    if rc:
        print(rc, end="")
    if delta.content:
        print(delta.content, end="")
```

Recommended sampling (matching Poolside's benchmark runs): **temperature=1.0, top_k=20**, thinking enabled.

To disable thinking, omit `--default-chat-template-kwargs` at launch, or pass `extra_body={"chat_template_kwargs": {"enable_thinking": False}}` per request.

### References

- [Model card](https://huggingface.co/poolside/Laguna-M.1)
- [Release blog post](https://poolside.ai/blog/laguna-a-deeper-dive)
- [Technical report](https://poolside.ai/assets/laguna/laguna-m1-xs2-technical-report.pdf)
- [vLLM support PR #41129](https://github.com/vllm-project/vllm/pull/41129)