வேல்

⚡ Vel

Apps your AI agent builds. Guaranteed by the framework.

The first framework where the primary developer is not human.

---

The Problem

Your AI agent can write code. But where does that code run? How do you know it won't break your server? How do you install someone else's agent-built tool without worrying?

Everyone's making agents smarter at writing code. Nobody's making a framework where that code is guaranteed safe.

The Solution

Tell your AI agent what you need. It writes two files. Vel compiles, sandboxes, validates, and serves.

If it builds, it works. If it doesn't build, the error tells you exactly what's wrong.

Agent writes:  app.json + ui.js
Vel does:      discover → validate → compile → sandbox → serve
You get:       a live dashboard panel with real-time data

---

Why Vel?

🤖 Agent-First

Built for AI developers from day one. JSON manifests (agents corrupt JSON less than code). Elm-quality error messages. This entire framework was built through a Telegram chat — no human wrote a line of code.

🛡️ Structurally Safe

The wrong code won't compile. Apps declare what they import, vel build enforces it at compile time. os/exec is blocked by default. In a world where hundreds of OpenClaw skills have been flagged as potentially malicious, Vel makes the unsafe path impossible.

🧩 Composable

Install anything. Remove anything. Nothing else breaks. Every app is independent. No dependency hell. No version conflicts. Add one, remove one — everything else keeps working.

⚡ Zero-Config Deploy

One Go binary. No Node.js. No Python. No Docker. No runtime dependencies. vel build → deploy anywhere.

---

Apps built on Vel

App	What it does	Install
VelMetrics	Server monitoring — CPU, memory, disk, processes	git clone into apps/
VelBridge	Your agent controls your browser. Pair with a code, watch it work.	git clone into apps/

These apps don't fork Vel. They don't conflict with each other. They compose. That's the point.

---

Quick start

# Set up project directory
mkdir my-vel-project && cd my-vel-project

# Clone the framework
git clone https://github.com/essdee/vel.git

# Configure
mkdir -p config
cp vel/config.example.json config/vel.json
# Edit config/vel.json with your bot token and user IDs

# Build and run
cd vel && go run . build && cd ..
BOT_TOKEN=your-token ./bin/vel

Open localhost:3700. That's it.

Add an app

cd apps/
git clone https://github.com/karthikeyan5/velmetrics.git
cd ../vel && go run . build && cd ..
./bin/vel

Reload the page. Six new monitoring panels appear. No config. No restart. Just rebuild and serve.

---

How apps work

An app is a folder with an app.json:

apps/my-app/
├── app.json           # Manifest — name, capabilities, routes
├── panels/            # UI panels (manifest.json + ui.js each)
└── server/            # Optional Go code (compiled into binary)

Apps can be panel-only (zero Go code, just UI) or ship full server-side logic. Either way: discovery, routing, auth, streaming, and error boundaries are handled.

The capability system

Apps declare what standard library packages they need:

{
  "capabilities": {
    "read": {},
    "write": {},
    "net": {}
  }
}

vel build scans the app's Go code and blocks any import not covered by declared capabilities. Your agent can't accidentally (or intentionally) import os/exec, syscall, or unsafe.

---

What's here today

• App discovery — drop a folder in apps/, rebuild, done
• Panel system — real-time WebSocket streaming, auto-layout, error boundaries
• Capability sandbox — compile-time import enforcement (Deno-inspired)
• Auth — Telegram HMAC-SHA256, API keys, magic links, signed cookies
• Build system — AST rewriting, capability wrappers, single binary output
• Debug server — localhost:6060 for diagnostics
• Health checks — vel verify + /api/health
• Frontend — Preact + HTM (5KB vendored), service worker, responsive layout

📋 Full feature inventory →

---

For AI agents

Vel ships with comprehensive agent instructions:

• Setup guide — Step-by-step install guide your agent can follow
• Building apps — How to build apps on Vel
• AI-native design — Why Vel is designed this way

Every error message tells your agent how to fix it, not just what broke. Convention over configuration means fewer decisions, fewer mistakes, fewer tokens wasted.

---

Docs

Doc	What it covers
AI-NATIVE.md	Design principles for AI-native development
CONTRACTS.md	Panel contracts, manifest schema, hooks, CSS
CONVENTIONS.md	Decision framework and naming
TESTING.md	Testing strategy and conventions
BUILDING-APPS.md	Build your first Vel app
AUTH.md	Comprehensive authentication & authorization reference

---

License

MIT

---

_{Vel (வேல்) — the divine spear of Murugan. Sharp. Fast. Unerring.}