Surfbots Dev Platform indexes the repository you are actively developing, preserves the decisions and unfinished work behind it, and adds profile-driven development supervision. Repository-scoped MCP tools give Cline and other coding agents current code evidence, historical context, task refinement, implementation checkpoints, active collaboration, change review, supervision status, and fail-closed task completion.
Released v0.5.0
The new release connects project rules, task evidence, model settings, and installer delivery. Cline and Copilot receive aligned rules, while the CLI carries substantial work through checkpoints, review, verification, and completion.
A scoped task records its repository and allowed files. Review uses canonical Git changes and test results; verification rejects changed evidence. Missing checkpoints, incomplete review, or unresolved findings prevent completion.
Set a context window for generation, reviewer, promptRefiner, and collaborator. Overrides survive profile storage, cloning, export, and import. Changing a role’s model resets its context override.
Managed generation uses one slot with the extra RAM prompt-state cache disabled. Embedding inference runs on one worker to prevent overlapping allocations. Memory changes are applied by activating an inactive profile.
| Model configuration | Context tokens | Managed model memory |
|---|---|---|
| Local Lightweight · Qwen | 8,192 | 6 GiB |
| Local Quality · Qwen | 32,768 | 6 GiB |
| Optional Devstral Small 2 24B Q4 | 32,768 | 32 GiB |
| Recognized OpenAI model IDs | 128,000, capped by the known model limit | Provider managed |
| Unknown, compatible, or Azure deployment IDs | 8,192 until configured | Server managed |
Context budgets include input, reserved output, and safety space. Increasing a budget does not enlarge an external server’s context window or memory. All managed local roles share one server allocation; leave additional memory for retrieval services, your IDE, other models, and the operating system. Devstral is optional and is not activated just by installing the release.
surfbots-dev models profile set-context <profile> reviewer 32768. Use default to restore the model default.surfbots-dev models profile set-memory <inactive-profile> 8, then activate it. Failed activation attempts to restore the previous deployment and reports rollback failures.surfbots-dev supervision status shows supervision state and token usage. Counters reset with the API process; persisted lifecycle records survive restarts.Across VS Code projects: repository IDs scope search, memory, and lifecycle evidence. In multi-root workspaces, choose the matching repository and run lifecycle commands from that Git root. Prefer generated task IDs. Model profiles and budgets are shared platform settings, not automatic per-project preferences.
Release validation: 425 automated tests passed, all seven services passed live health checks, and the published archive and SHA-256 checksum were verified. Batched review covers changed files but does not jointly analyze cross-batch interactions. Read the release notes and validation limits.
Agent-ready infrastructure
The coding agent can change. The model can change. Surfbots keeps a persistent development layer underneath them: current repository truth, durable engineering context, and model-assisted supervision that turns requests into implementation specifications and reviews completed changes.
Current truth. Surfbots refreshes a managed snapshot of the registered working tree, then parses, embeds, and searches the code currently being developed without exposing arbitrary host paths to Kubernetes.
Historical intent/context. A separate session-memory index preserves concise decisions, completed work, validation results, and unresolved items so a new agent session can recover why the code evolved.
Specification and review. Model-assisted MCP tools refine substantial requests into implementation specifications, provide active development guidance during implementation, and review completed changes for missed requirements, regressions, architecture violations, and missing tests.
Autonomous indexing
Surfbots keeps Kubernetes access intentionally constrained: the host CLI refreshes an atomic managed snapshot, then the indexer works only from that snapshot. Successful reindex requests can also record a compact lifecycle checkpoint for the next agent session.
surfbots-dev repo add . records an immutable repository ID and canonical local root.MCP-native engineering intelligence
Use the scoped CLI lifecycle for substantial work; the MCP tools below provide retrieval and supervision capabilities rather than replacing its Git-evidence gates. Agents do not need to understand Qdrant, embeddings, repository bookkeeping, or supervision internals. They call bounded, repository-scoped MCP tools that expose the evidence needed for the current engineering decision while Surfbots maintains persistent code and task context underneath the agent.
| Capability | Tool | Purpose |
|---|---|---|
| Code Intelligence | search_code | Find semantically relevant implementation evidence without rereading the repository. |
| Code Intelligence | get_file | Retrieve bounded file content from the registered repository. |
| Code Intelligence | get_file_range | Read a bounded line range for precise implementation evidence. |
| Code Intelligence | find_symbol | Locate symbol definitions before making changes. |
| Code Intelligence | find_references | Understand impact by finding symbol usage across the repository. |
| Repository Context | repository_status | Confirm repository identity, indexing state, and current context before work begins. |
| Development Memory | get_recent_context | Recover bounded recent decisions, completed work, validation results, and unresolved items. |
| Development Memory | search_repository_memory | Search historical rationale by task, file, symbol, or engineering topic. |
| Development Memory | write_repository_memory | Persist concise engineering checkpoints for continuity across sessions and agents. |
| Development Supervision | refine_task | Turn a substantial request into a repository-aware implementation specification with constraints, tests, and acceptance criteria. |
| Development Supervision | collaborate_task | Bring in the model selected by the supervision profile for architectural choices, blockers, conflicts, and deeper implementation guidance. |
| Development Supervision | development_task_checkpoint | Require meaningful supervisory collaboration at investigation, implementation, testing, failure-analysis, milestone, and pre-review boundaries. |
| Development Supervision | review_changes | Review completed work against the task specification, current code, architecture, and test evidence. |
| Development Supervision | development_supervision_status | Expose checkpoint state, missing actions, model provenance, calls, and token usage for the active task. |
| Development Supervision | complete_development_task | Close a task only when persisted refinement, required checkpoints, review evidence, and an acceptable verdict prove completion. |
Code, engineering memory, checkpoint state, refinement evidence, and review evidence are persisted independently from the coding agent's temporary conversation.
Development Supervision is profile-driven rather than tied to one model. A profile can use a local model for fully private operation or a remote provider such as OpenAI when that is the preferred deployment model. Code Intelligence and Development Memory remain the same while the generation and supervision provider can change independently.
Substantial tasks can be configured to fail closed: completion requires the expected refinement, checkpoint, and review records rather than a self-declared “done” state.
Supervision records are task- and repository-scoped. Dedicated evidence types separate refinement, collaboration, review, and workflow state, while strict same-type supersession maintains an auditable chain of the latest authoritative record. Runtime provenance records which model/profile actually performed the supervisory work.
Development Supervision
Surfbots does not replace the coding agent. It adds structured profile-driven AI collaboration around the agent's work so substantial changes can be specified, challenged, tested, reviewed, and closed against persistent evidence.
surfbots-dev task begin <repository_id> "Describe the task" --expected-files <files> refines the request and creates a task with acceptance criteria and a defined scope.surfbots-dev task checkpoint at post-investigation, post-implementation, post-test, and pre-review boundaries. Record failure analysis when needed.surfbots-dev task review <task_id> --test-results @results.txt submits the canonical Git evidence. Missing coverage or unresolved findings block a clean result.surfbots-dev task verify <task_id> --test-results @results.txt checks required records and confirms that the working tree and test evidence match the review.surfbots-dev task complete <task_id> closes a verified task. Check surfbots-dev task status <task_id> for completion and any missing actions.Start a new Cline task/session after installing the updated rules. Select the correct repository root before beginning substantial work; direct MCP supervision calls do not replace the CLI lifecycle.
Local-first runtime
CLI, configuration, metadata, snapshots, and runtime state live under the developer's user directories such as ~/.local and ~/.config.
Qdrant, Code Intelligence, MCP, embedding, generation, reranking, and supervision services run in the local Kubernetes environment while repository access remains intentionally host-scoped.
The public installer downloads a release archive and verifies its SHA-256 checksum. The CLI performs idempotent setup, upgrades, diagnostics, and lifecycle management.
Practical local footprint
The core local workload is Code Intelligence: repository indexing, Qdrant, the embedding model, and the reranker. Generation and Development Supervision are selected through profiles and can use either a local model or a remote provider such as OpenAI. That means teams can keep repository retrieval local without requiring the developer PC to host a large coding or supervision model.
4 modern 64-bit CPU cores minimum; 8+ recommended. CPU capacity primarily affects indexing, embeddings, reranking, Kubernetes services, and concurrent development workloads.
16 GB RAM minimum; 32 GB recommended. This provides practical headroom for Kubernetes, Qdrant, the local embedding and reranking models, your IDE, and active repositories. A remote generation/supervision profile avoids the additional memory burden of a large local LLM.
25 GB of free SSD space as a practical starting point. A discrete GPU is not required for the baseline Code Intelligence stack. GPU resources become relevant when you choose to run larger generation or supervision models locally.
Flexible by design: keep embeddings, reranking, repository indexes, and Development Memory local while choosing the generation/supervision profile that fits the environment. Use a lightweight local model, a larger local model, or an approved remote provider without changing the repository intelligence layer.
Download the bootstrap, inspect it, then run it. It checks the local toolchain and hardware, installs into your XDG user directories, deploys the local Kubernetes stack, verifies MCP, and configures Cline and Copilot without overwriting their existing MCP settings.
curl -fsSL https://www.surfbots.ai/surfbots-bootstrap.sh -o /tmp/surfbots-bootstrap.sh && bash /tmp/surfbots-bootstrap.sh
Profiles control generation and supervision. The baseline local stack keeps Qwen3 embeddings, BGE reranking, Qdrant, and repository intelligence on the developer machine. Generation and supervision can then be assigned to a lightweight local model, a larger local model, or a configured remote provider such as OpenAI. This keeps the Code Intelligence footprint practical while allowing teams to choose the model/provider that best fits privacy, quality, cost, and hardware requirements.
Download Bootstrap Inspect Bootstrap Public Release Repository. Linux is currently supported. Required tools: curl, Git, rsync, Docker, kubectl, k3d, Helm, and Python 3. The installer never silently uses sudo or installs operating-system packages.