Introduction

Pathvela is an open agentic framework — open to use, integrate, and embed. It is not open source: you don't run or host the model, and you don't wire up a stack of infrastructure. You bring an API key, and you get a capable agent that can read, reason, call tools, and get real work done.

The defining idea is one agent, two surfaces:

• In your terminal, the CLI runs the agent right where you work — in your project folder, with real files and a real shell.
• In your app, the SDK (@poolot/lily-web) runs the identical agent in the browser (WebAssembly) or on Node.

Both surfaces talk to the same Pathvela backend, run the same models, and are metered on the same Pathvela account. Whatever you learn on one carries over to the other.

Why an agent, not just a model

A model completes text. An agent runs a loop: it reads your request, decides what to do, calls tools (read a file, run a command, search, fetch a page), observes the results, and keeps going until the task is done. Pathvela handles that loop for you — the planning, the tool calls, the retries, the budget limits — so you describe the goal and get an outcome.

What the agent can do

Out of the box the agent can work with real things, not just answer questions:

• Read and edit files — open the files in your project, understand them, and make changes across several at once.
• Run commands — execute shell commands and read their output, so it can build, test, run scripts, and act on what happened.
• Search and navigate — find code, files, and text across a project instead of needing you to point at everything.
• Fetch the web — pull in a page or a docs URL when a task needs outside information.
• Remember context — keep track of what it's learned during a task and carry useful facts forward, so a long job stays coherent.

Which of these are available depends on where the agent runs — a terminal or server has a real filesystem and shell, while a browser runs in a sandbox. Browser vs Node lays out exactly what each environment can and can't do.

You don't wire any of this up. You give the agent a goal in plain language, and it decides which tools to use and in what order.

The CLI

The CLI is the agent as a local companion. You install it once, run it inside a project, and it can work with your files and shell. It can also run as a background service — auto mode, enabled with lily bridge install — so your Pathvela browser tab or app can reach the agent on your machine. See the CLI overview.

lily run "Explain what this repo does and where the entry point is"

The SDK

The SDK is the agent as a building block. You call createLilyAgent(...) and get back an agent handle you drive from your own code — streaming tokens into your UI, subscribing to events, and reading structured results. The whole agentic loop can run client-side in the browser from a small WebAssembly engine, or on Node for server workloads. See the SDK overview.

const agent = await createLilyAgent({ apiKey, model: 'poolot-standard' })
const result = await agent.runDetailed([{ role: 'user', content: 'Summarize this document.' }])

Models

Pathvela exposes a small set of model tiers, selected with the model option:

You never manage a raw provider or model name — you pick a Pathvela tier and the backend routes it.

Where to go next

• New to Pathvela? Start with the Quickstart.
• Want the agent in your terminal? Read the CLI overview.
• Building a product? Read the SDK overview.