Agen
Start here / Getting started

Start here

Getting started

In about ten minutes: run a local fleet, deploy an agent, then give one a real model and a real tool, and see what it did. You need nothing but Agen for the first part.

1. Install

curl -fsSL https://prjvvl.github.io/agen/install.sh | sh

On Windows, in PowerShell: irm https://prjvvl.github.io/agen/install.ps1 | iex. Open a new terminal and check it with agen version. Install has the details.

2. Start a local fleet

agen up
agen is up: hub http://127.0.0.1:7070 (credentials in ~/.agen/local.json)
web UI: http://127.0.0.1:7070/ (run 'agen ui' for a sign-in link)

agen up runs a Hub (the control plane) and one Nest (which runs agents) on your machine and keeps running; use a second terminal for the rest. Concepts explains the words.

3. Deploy an agent

agen init
agen deploy hello --replicas 1
agen run hello "hi"
wrote the hello template to hello
next: agen deploy hello --replicas 1
deployed default/hello definition <digest> desired 1
Hello! Nice to meet you.

agen init writes an example agent (a “bundle”) into ./hello. Its model is scripted, so this works without an API key; the reply is canned. Look at the files: x-agen/agent.md is the system prompt, x-agen/harness.json picks the model, x-agen/config.json sets scaling and permissions.

4. A real model and a real tool

The researcher example answers questions by reading web pages, with a model on OpenRouter and the fetch MCP server as its tool. It needs an OpenRouter API key (this walkthrough costs well under a cent) and uv, which runs the tool server.

Agents get their keys from the environment of agen up, so stop it (Ctrl+C in its terminal, or agen down), set the key, and start it again:

agen down
export OPENROUTER_API_KEY=sk-or-...
agen up

On Windows: $env:OPENROUTER_API_KEY = "sk-or-..." before agen up. Then, in the second terminal:

agen init --template researcher
agen deploy researcher --validate
agen deploy researcher --replicas 1
agen run researcher "What is the title of the page at https://example.com?" --conversation demo --label project=docs
agen run researcher "Which URL did you read in my previous question?" --conversation demo
bundle is valid
deployed default/researcher definition <digest> desired 1
Example Domain
https://example.com
  • --validate checks a bundle and warns about likely mistakes without deploying it.
  • Both tasks use the conversation key demo, so the second sees the first (see Memory). Without --conversation every task starts fresh.
  • The label travels with the task to its run, trace and tool calls.

5. See what happened

agen ps --all
agen tasks researcher
agen logs researcher
agen trace <task-id>
agen transcript <task-id>
agen ui

agen ps --all shows each instance and how many tools it loaded; the trace shows every model call and tool call with its timing; the transcript shows what the agent sent to the model and got back, tool results included; the logs show the instance starting and each run’s token usage. agen ui prints a sign-in link for the console, which shows all of it live, from a map of the fleet down to a single model call.

6. Clean up

agen rm researcher
agen rm hello
agen down

Next