Based on AgentRun release · Synced .
Run your first agent
Start AgentRun locally, add a model key, and run an agent from the console. You will have one place to manage its instructions, runs, results, and learning.
Before you start
- macOS or Linux, with Node.js 22.19+ on the 22 release line, or 24.2+ and npm.
- One model API key. A capped OpenRouter key is a convenient starting point. An Anthropic or OpenAI API key also works. Your coding app's subscription does not supply a model key to this server.
- Docker is optional for the first task below. Add it when your agents need a shell. Docker must be running and accessible to the user starting AgentRun; the first box image build can take a few minutes.
Check Node:
node --version
This quickstart runs the published launcher, @parcha/agentrun on its 0.4 line, which installs its matching server. The platform guides and source references also describe newer work on GitHub main; check your server's capabilities before using a newer feature.
1. Start the server
npx @parcha/agentrun@0.4
Keep this terminal running. AgentRun opens its console in your browser and prints its address. It uses the first free local port starting at 7340 and stores data in ~/.agentrun.
Open the printed address, rather than assuming a port. Set your console password on the first visit. For a machine without a browser, use --no-open and access the console through your existing SSH tunnel.
2. Add your model key
In Settings, open Model keys under Tool keys, choose your provider, and save its key. The saved key takes effect without a restart. Keep the key in this form or your secret manager; do not paste it into a chat or commit it to a project.
AgentRun can also use OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY already set in the environment where it starts. You do not need a separate decision-provider key for this first task.
If the console says no model is available, see Models and API keys.
3. Create an agent
Open Agents → New agent and use:
| Setting | Value |
|---|---|
| Name | Release notes |
| Harness | Pi, included with the server |
| Instructions | Write concise release notes from the changes I provide. Group them into Added, Changed, and Fixed. Do not invent changes. |
| Model | The available server default |
| Tools | None needed for this task |
Save the agent. The harness runs its reasoning; AgentRun manages its definition, execution, history, and results. You can choose a different available harness later without changing how you start or inspect runs.
4. Start a run
On the agent's page, choose Start a run. Give it this input:
Write release notes for these changes:
- Added CSV export to the runs page.
- Fixed the date filter resetting after refresh.
- Renamed the workspace settings page to Settings.
Review the model and spend cap before starting. This step calls your model provider and uses its credits.
Follow the timeline until the run completes. The result should contain the three supplied changes, grouped under Added, Changed, and Fixed. Open Runs to find the same run again and inspect its result and recorded usage. Reloading the console should preserve it.
5. Turn on learning for repeated work
Once the first run works, enable Learning on the agent. Give it several similar tasks and inspect what it proposes to retain. Later runs can reuse accepted notes, skills, and workflows. Learning has its own cost; one short run is not a meaningful savings benchmark.
Continue with Agents and runs, then Self-improving agents.
If something blocks the first run
| What you see | What to check |
|---|---|
| Unsupported Node version | Use a supported Node release, then start the launcher again. |
| No model or a provider authentication error | Save the key for the selected model's provider in Settings. Check the provider's credit balance. |
| A harness is unavailable | Use Pi for this first run. The server's capability response explains additional harness requirements. |
| Preparing the Docker image | Let the initial build finish if you chose a box with shell tools. It needs network access and disk space. |
| An older data directory is refused | Preserve it and use its original server version. Start a new version with a separate --data directory; see Back up and move your server. |
For an agent-assisted setup, use the setup instructions. For the exact launcher behavior, see the CLI reference.