Built by DARKSOL 🌑

Darksol Studio

Local-first AI agent engine with autonomous tool calling, hardware-aware inference, OpenAI-compatible API, and MCP integration. One npm install — your models, your machine, your agent.

Website · GitLab · npm

What's New in v0.4.0

Deep Agent — a full autonomous coding agent system built into the engine. Zero external dependencies. Works with any OpenAI-compatible model (local or remote).

# Give it a task — it plans, reads files, writes code, runs commands
darksol agent "Build a REST API with user authentication"

# Interactive mode — persistent conversation with tool access
darksol agent --interactive

# Use any model
darksol agent --model ollama/qwen3:30b "Refactor src/ to use TypeScript"

The agent has access to filesystem tools (read, write, edit, glob, grep), shell execution, a planning system (persistent todos), auto-summarization when context gets long, a skills library, persistent memory via AGENTS.md, and sub-agent spawning for parallel work.

All of this also works through the API (POST /v1/agent/run) and the web shell (🤖 toggle in the chat header).

Install

npm i -g darksol

Quick Start

# Run the agent on a task
darksol agent "Analyze this codebase and write a summary"

# Search for models (with hardware fit check)
darksol search llama --limit 5

# Pull a model from HuggingFace
darksol pull llama-3.2-3b-gguf

# Run a one-shot prompt
darksol run llama-3.2-3b "Write a haiku about local inference."

# Use an existing Ollama model directly
darksol run ollama/llama3.2:latest "hello world"

# Start the API server + web shell
darksol serve
# → http://127.0.0.1:11435

Both command aliases work: darksol-studio and darksol.

Deep Agent

The agent system gives your local models the ability to plan, read and write files, execute commands, and break complex tasks into sub-tasks — all autonomously.

How It Works

1. You give it a task
2. It creates a plan (write_todos)
3. It uses tools to complete each step (read_file, write_file, edit_file, execute, glob, grep)
4. It auto-summarizes when context gets long
5. It returns the final result

Agent Tools

Middleware Stack

The agent ships with a full middleware pipeline — each piece is opt-in and composable:

• Planning — Persistent task lists (write_todos) injected into system prompt each turn. Tasks track pending → in_progress → completed.
• Auto-Summarization — Monitors context usage (85% threshold). When triggered, old messages are compressed into a summary, full history is offloaded to ~/.darksol/conversation_history/, and the agent keeps working with a fresh context.
• Skills — Discovers SKILL.md files from ~/.darksol/skills/ and ./skills/. Uses progressive disclosure: names + descriptions in the prompt, full instructions loaded on demand. Compatible with the Agent Skills spec.
• Memory — Loads AGENTS.md files as persistent context. The agent can update its own memory via edit_file. Compatible with the agents.md spec.
• Sub-Agents — The task tool spawns isolated child agents with fresh context windows. Each sub-agent gets the same tools but its own conversation. Supports parallel execution.

CLI Usage

# One-shot: give a task, get a result
darksol agent "Create a Node.js Express server with health check endpoint"

# Interactive: persistent conversation with planning
darksol agent --interactive

# Choose your model
darksol agent --model ollama/qwen3:30b "Review this PR for security issues"

# Set working directory
darksol agent --cwd ./my-project "Add unit tests for src/utils.js"

# Verbose mode: see every tool call
darksol agent --verbose "What files are in this project?"

API Usage

# Non-streaming
curl -X POST http://127.0.0.1:11435/v1/agent/run \
  -H "content-type: application/json" \
  -d '{
    "message": "List all JavaScript files and count lines of code",
    "model": "llama-3.2-3b",
    "planning": true
  }'

# Streaming (SSE events: thinking, tool_call, tool_result, response, done)
curl -X POST http://127.0.0.1:11435/v1/agent/run \
  -H "content-type: application/json" \
  -d '{
    "message": "Build a calculator module with tests",
    "stream": true
  }'

# List available tools
curl http://127.0.0.1:11435/v1/agent/tools

Web Shell

Start the server with darksol serve, open http://127.0.0.1:11435, and click the 🤖 Agent toggle in the chat header. You'll see real-time tool calls, results, and thinking indicators as the agent works.

Programmatic Usage

import { createDarksolAgent } from "darksol/src/agent/deep-agent.js";

const agent = createDarksolAgent({
  model: "llama-3.2-3b",
  apiBase: "http://127.0.0.1:11435",
  planning: true,
  skills: true,
  memory: true,
  subagents: true,
  cwd: "./my-project",
});

const result = await agent.run("Build a REST API with CRUD endpoints");
console.log(result.response);
console.log(`Completed in ${result.iterations} iterations`);

Features

• 🤖 Deep Agent — autonomous task completion with planning, filesystem, shell, and sub-agents
• ⚡ Hardware-aware inference — auto-detects GPU, VRAM, CPU, RAM and optimizes settings
• 🔌 OpenAI-compatible API — drop-in /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings
• 🦙 Ollama model reuse — finds and runs your existing Ollama models directly, no daemon required
• 🔍 HuggingFace directory — browse, search, and pull GGUF models with "will it fit?" indicators
• 🔧 MCP tool integration — connect external tools via Model Context Protocol
• 🧠 Skills system — progressive disclosure skill loading (Agent Skills spec compatible)
• 📝 AGENTS.md memory — persistent context across sessions
• 🗜️ Auto-summarization — never hit context limits, history offloaded to disk
• 💰 Cost tracking — every local inference is $0.00, track usage and savings vs cloud
• 📡 SSE streaming — real-time token streaming with abort support

CLI Commands

API Endpoints

Default: http://127.0.0.1:11435

Agent

Chat & Inference

Models & Discovery

Runtime & Config

MCP

Bankr Gateway

MCP Integration

Darksol supports the Model Context Protocol for connecting external tools to your models. Pre-configured servers:

• CoinGecko — crypto prices and market data
• DexScreener — DEX trading pairs and analytics
• Etherscan — Ethereum blockchain data
• DefiLlama — DeFi protocol TVL and yields

Enable with darksol mcp enable <name>. Config: ~/.darksol/mcp-servers.json.

Environment

Runtime config: ~/.darksol/config.json

NVIDIA NIM

Cloud inference via NVIDIA NIM — access Llama, Mistral, Nemotron, and other models through NVIDIA's OpenAI-compatible API.

# Set your API key (free tier available at build.nvidia.com)
export DARKSOL_NVIDIA_API_KEY=nvapi-...

# List available models
darksol nvidia models

# One-shot prompt
darksol run nvidia/meta/llama-3.1-8b-instruct "Explain quantum computing"

# Interactive chat
darksol nvidia chat meta/llama-3.1-70b-instruct

# Compare NIM vs local model
darksol compare nvidia/meta/llama-3.1-8b-instruct ollama/llama3.2:latest

Desktop + Web Shell

Web Shell

Start the server and open http://127.0.0.1:11435 for the interactive web shell with:

• Model browser with hardware-fit indicators
• Chat panel with SSE streaming
• Agent mode toggle (🤖) with real-time tool event display
• Settings panel with runtime controls, MCP toggles, Bankr config

Desktop App

# Dev mode
npm run desktop:dev

# Build installers
npm run desktop:build:win   # Windows NSIS
npm run desktop:build:mac   # macOS DMG (Intel + Apple Silicon)

License

MIT

Built with teeth. 🌑