Frequently asked questions.

Krelvan is a self-hostable, open-source platform for building and running AI agents you own. You describe a goal in plain English; Krelvan builds a real agent, shows you the plan before anything executes, runs it on your machine, and keeps a complete, replayable record of every step it took.

The core idea: the canvas is the runtime. Every step of a run is a real recorded event, and the visual canvas, the run timeline, and the history are all direct reads of that one record — so what you see is exactly what executed.

Yes. Krelvan is Apache-2.0. You self-host it on your own machine, run it for yourself, your team, or your clients, extend it, and own what you build.

No. This public website is a read-only product and registry surface; it does not provide shared customer workspaces. The API, web UI, agents, and data run in your own Krelvan installation.

The sign-in screen belongs only to a downloaded installation. It protects that installation's single workspace with the admin credential created during first-run setup.

The fastest path is Node 22+ and npx krelvan@0.1.2. The version is explicit so a later release cannot replace the package you reviewed. For a container install, download the versioned docker-compose.release.yml from the GitHub release and start it with Docker Compose. The Download page has copyable commands for both paths and for the signed tarball.

The npm launcher's first start builds the web UI and can take a few minutes; later starts reuse that build. It opens at localhost:3100 and stores persistent data in ~/.krelvan unless you set another data directory.

The terminal prints a one-time setup token and the local URL. Open the URL, paste that token, and create the admin account for this installation. Then open Settings → Model & secrets, connect a model, and return to the Dashboard to build an agent.

The admin account is local to this installation. It is not a krelvan.com account, and the public website does not receive your credential, agents, or run data.

For the npm launcher, Ctrl-C stops the API and web UI; run the same versioned command again to restart. Your admin account, model configuration, agents, memory, and records survive because they live in ~/.krelvan by default.

Back up the entire data directory before changing versions, including its identity and secret-key files. Container installs keep the same state in the krelvan-data volume. Review the target release notes, back up, then start the new immutable version.

No. The web UI and API boot with no secrets at all — the app runs and clearly reports that LLM features are off. Building agents, run explanations, and failure diagnosis switch on when you connect a provider: either an API key, or a local Ollama model with no key and no network.

In most systems, execution happens somewhere and a log is written about it afterwards — and the two can drift. In Krelvan the visual canvas, the run timeline, the history, and even agent memory are all direct reads of the same recorded run. There is no separate “what happened” store that could disagree.

That single design choice is why “what you see is exactly what executed” is structural rather than hopeful — there is nothing else the UI could be showing you.

Yes. Every step of a run is recorded as a real event, so you can scrub back through any run step by step and see precisely what the agent read, decided, and did — the same view whether the run finished a minute ago or last month.

It resumes safely. The run's state lives entirely in its recorded history, so resuming is just re-reading it: the engine sees exactly which steps completed and continues from there. Side effects use a three-step protocol (intent, execution, result), which guarantees an irreversible effect — sending an email or calling an external API — runs exactly once, never twice, even if the process dies mid-step.

There's a runnable demo: npm run demo:resume kills a run mid-flight, resumes it, and shows each irreversible effect executed exactly once.

No. It proves the record is complete and untampered: which inputs, tool results, model calls, decisions, and outputs actually occurred. A model can still misunderstand a source or produce an unsupported conclusion.

Use the recorded source values and intermediate steps to review important answers. For high-consequence work, add an independent checking step or require a person to approve the result. Krelvan never labels cryptographic integrity as factual accuracy.

Seven, behind one client: Anthropic, OpenAI, Google Gemini, Groq, Mistral, Ollama (fully local), and any OpenAI-compatible endpoint — so a self-hosted gateway or another vendor's compatible API works too. The provider is configuration, not architecture: you can switch without rebuilding your agents.

In your downloaded installation, open Settings → Model & secrets. Choose the provider, enter the model, add a key when that provider needs one, and set a base URL for Ollama or an OpenAI-compatible endpoint. The Dashboard links here automatically when no model is connected.

The value is encrypted on your instance and is never shown in full again. For unattended deployments you can use the documented KRELVAN_LLM_PROVIDER, KRELVAN_LLM_MODEL, KRELVAN_LLM_API_KEY, and KRELVAN_LLM_BASE_URL environment variables instead.

Yes. Set the provider to Ollama and Krelvan runs against a model on your own hardware — no API key, no network calls to any model vendor. RAG works fully local too: rag.ingest and rag.search can use local embeddings via Ollama, so a document-grounded agent can run entirely offline.

Only where you point it. Krelvan is self-hosted: your agents, your runs, and your documents live in your own data directory. The only outbound calls are the ones you configure — your chosen model provider, plus whatever capabilities you explicitly grant (an HTTP API, an MCP server). With Ollama, even the model calls stay on your machine.

Secrets are encrypted at rest with AES-256-GCM, and they never enter plugin code — a broker injects them at the destination on the host.

Only to the degree you allow. Every step has an autonomy level — suggest (propose only), act-with-veto (act, but pause first on anything risky), or full. Independently, every capability declares a side-effect class, and irreversible or spend-class actions pause for human approval and show you the exact action it wants to take, not a summary.

Capabilities are deny-by-default: one that was never granted never runs, no matter what the model asks for.

They are hard execution allowances enforced before a step runs. Each run and capability carries a ceiling; Krelvan reserves the projected allowance before dispatch and settles it from the observed result afterwards. A step that would exceed a ceiling is refused before it starts, including when several calls run concurrently.

Honestly: no agent platform can make prompt injection impossible, and we won't claim otherwise. What Krelvan does is bound the blast radius with mechanical guards: capability monotonicity in the compiler (content an agent read can never widen what the agent is allowed to do), untrusted inbound content is quarantined in memory with provenance, conditional logic is a restricted typed-AST evaluator — there is no eval anywhere — and outbound HTTP goes through an allowlisted, SSRF-guarded egress channel.

And because every step is recorded, if something does go wrong you can see exactly what happened, after the fact.

By trust tier. Declarative YAML capabilities and MCP connectors are data, not code — safe by construction. Untrusted TypeScript plugins run in a real OS-process sandbox (node --permission): filesystem writes, child processes, native addons, workers, and WASI are denied, with memory and timeout caps and a scrubbed environment.

Plugins reach the network only through the brokered, allowlisted, SSRF-guarded channel; secrets never enter the plugin process; and a supervisor co-signs what it mechanically observed — a plugin can never sign facts about its own behaviour. This sandbox is adversarially tested.

Describe the outcome in plain English. Krelvan compiles that into a validated, typed agent graph — the model acts as a compiler into a manifest the kernel runs; it never executes free-form code — and shows you the plan before anything runs. Approve it, run it, and open the full run history.

You can also start from a ready-made template in the marketplace — a price monitor, a RAG support bot, a knowledge-base ingester — and make it yours.

Yes — that's an intended use, and Apache-2.0 permits it commercially. The fastest path: install a template (say the RAG support bot), then use its customize surface to rename it, point it at the client's knowledge base, and set their tone and autonomy limits. Each clone is baked into a fresh manifest and installed as its own independent agent.

When you deliver, the client can see exactly what the agent did — every run keeps a complete, replayable history they can scrub through step by step.

Four extension surfaces, ordered by effort. A YAML capability wraps any HTTP API with no code. An MCP connector plugs in any MCP server — every tool it exposes becomes a capability. A TypeScript plugin (sandboxed, as above) covers anything custom. And an agent template packages a whole working agent — the graph, its capabilities, and the secrets it needs — installable in one click.

The marketplace itself is a public Git repository, not a hosted catalog: publishing means opening a pull request, and a validator — the same one the runtime uses — gates every entry, so a broken capability can't reach the Discover tab.

Krelvan doesn't just retry — it reasons about the failure. It reads the full history of the failed run to find the root cause and the failing step, drafts a corrected agent from that diagnosis, and re-runs it. The repair attempt is recorded too, pass or fail, so the fix is as inspectable as the failure.

Yes. Cron and interval schedules run agents unattended — a price watcher every hour, a digest every morning. Scheduled runs go through exactly the same pipeline as manual ones: same budgets, same approval gates, same complete run history.

Single-tenant: an install is one workspace. There is no multi-tenant store yet (a PostgreSQL adapter is on the roadmap), so “one team, one box” is the deployment model today.

Self-host only: there is no hosted edition. If you want Krelvan, you run it — which is the point, but it does mean you administer it.

Before Krelvan asks Ollama to load a model, it checks host memory and the model metadata available from Ollama. The request is refused when projected host use would cross the configured ceiling, which defaults to 85%. This is a preflight guard; operating-system and Ollama limits remain the final enforcement boundary.

Some edges are still growing: messaging channels are send-only today (an agent can message you; you can't reply to drive it), and the canvas shows and replays agent graphs but isn't a drag-to-edit editor yet.

We'd rather under-claim. This is an early release, and the status section of the README marks exactly which parts are battle-tested. The load-bearing core — the event-sourced kernel, the run history and replay, the resume-after-crash protocol, and the plugin sandbox — is the most heavily tested part of the system, including adversarial tests. Strict typecheck and the test suite run clean.

Judge it yourself: the code, the tests, and a premortem doc enumerating failure modes (each with its guard and status) are all public in the repository.