For developers

Agents are files. The runtime is a container.

Everything the console does, you can do from a terminal, an editor and git.

AgentKube is a Node runtime shipped as one container image. It watches a folder of markdown agents, runs them with the model provider you configure, exposes an HTTP API and serves the console and the widget. You bring the model, the infrastructure, the data and the actions.

Quick start

A runtime on your laptop in under a minute

# 1. get the bundle from onboarding, or clone the repo
# 2. put a provider key in .env (GEMINI_API_KEY=… or OPENROUTER_KEY=…)
$ docker compose up -d
$ open http://localhost:4000

# the same with Podman
$ podman compose up -d

The agent file

One markdown file per agent: frontmatter for the name, description, model, tools, skills and knowledge; a body of numbered steps with a mode, instructions, captures, do rows and branches.

HOW IT WORKS

---
name: billing-questions
description: Answers invoice questions and processes approved refunds
tools: [lookup-invoice, apply-refund]
---
# Step 1: Identify
mode: guided
Ask for the invoice number.
- capture: invoice
- else -> do lookup-invoice(id={invoice}), step 2

# Step 2: Explain
mode: guided
Explain the charge from the result.
- if like "wants a refund" -> step 3
- else -> end

Embed SDK

Put the builder in your own app with one element, or the chat widget on any page with one script tag. Both talk to your runtime.

HOW IT WORKS

MCP servers

List your MCP servers in .mcp.json; agents name the tools they may call. Tool files under tools/ are served by the business MCP server that ships in the image.

HOW IT WORKS

{ "mcpServers": {
  "northwind-tools": { "url": "http://mcp:3999/mcp", "agentkube": true },
  "crm": { "url": "https://crm.example.com/mcp", "headers": { "Authorization": "Bearer ${CRM_TOKEN}" } }
} }

Import

The folder follows existing conventions: SKILL.md skills, markdown agents with frontmatter, AGENTS.md, .mcp.json. A folder that works in Claude Code or OpenClaw opens here, and the reverse.

HOW IT WORKSAgentKube adds only a builder: block in the frontmatter and the step grammar in the body; other hosts ignore the former and read the latter as instructions.

Docs

The specs are in the repository under docs/public/reference: the agent file, tools, providers, deploy targets, the widget, the runtime API.

HOW IT WORKSRead the docs on GitHub →

Build your first agent today

Run the runtime locally, describe a process, and have a tested agent in an afternoon.

Quick start Talk to us

FAQ

Questions people ask

How do I run AgentKube locally?

Download the bundle for a local environment from onboarding, or clone the repository, put a provider key in .env and run docker compose up -d. The console opens on port 4000.

What is the agent file format?

A markdown file with YAML frontmatter (name, description, model, tools, skills, knowledge) and a body of numbered steps. Each step has a mode, instructions, what to capture, do rows that call tools, and branches that name the next step, a handoff or the end.

Can I use my own editor and git?

Yes. The folder is plain files. The console and your editor touch the same files; git is your version control.

Does AgentKube have an API?

Yes. Every console action is an HTTP route under /api on your runtime, authenticated with a session or an API key with the api scope. Server-sent events stream conversations.