vakula

Why this exists

Generating Go code with an LLM is easy. Running it safely on your machine is not. Vakula is a forge daemon: drop a task file into an inbox, and an agent works the prompt until it produces validated code or exhausts its tool budget.

Named after the Slavic folklore blacksmith who sits at his forge and builds — appropriate for a process that waits for work and ships artifacts.

How it works

1. fsnotify watches data/in/ for new files (create events only — move or copy tasks in, do not edit in place).
2. The file body becomes the prompt; the basename (without extension) is the task ID.
3. A langchaingo conversational agent (Gemini or OpenAI) runs a ReAct loop with up to 10 iterations.
4. Two tools:
   • go_interpreter — compile and run generated Go inside an ephemeral Docker container
   • project_exporter — write a multi-file project to data/out/<taskID>/

The sandbox

LLM output is untrusted. Path writes are validated against traversal — including escapes after filepath.Join. Execution runs in golang:1.26-alpine with:

• Network disabled
• 512 MB memory cap
• Ephemeral temp directory — removed after every run
• Deferred container removal — cleanup even on panic

Generated code never gets direct host filesystem access during execution. Export to data/out/ is a separate, validated tool call.

Layout

Path	Role
data/in/	Task inbox (watched)
data/out/<taskID>/	Exported projects
internal/agent/	LLM agent loop and provider factory
internal/executor/	Docker sandbox and project exporter
internal/task/	Task file parsing

Provider and model are set in cmd/main.go (agent.Config). Default: Gemini with a Go-architect system prompt. Requires GOOGLE_API_KEY or OPENAI_API_KEY depending on provider.

cp .env.sample .env
go run ./cmd
# Vakula is at the forge. Press Ctrl+C to stop.

What it is not

Not a general-purpose coding assistant UI. A single-process daemon with a file-based task queue and a hard execution boundary — Docker Compose simplicity applied to agent tooling.