Getting Started

Getting Started

This page covers the fastest ways to run AgentDesk and the first demo path new users should follow.

Requirements

• Node.js 20.19.0 or newer.
• A modern browser.
• Optional: Ollama running on 127.0.0.1:11434 if you want live local model execution.
• Optional: OpenAI or Anthropic API key if you want Cloud BYOK model-node execution.

Run From NPM

Use the published package:

npx --yes --package=@papaplus/agentdesk agentdesk --port 5173

Open:

http://127.0.0.1:5173

This serves the built app through the packaged loopback CLI. It is the best path for users who want the local Runtime mode available.

Run From Source

git clone https://github.com/karurikwao/agentdesk.git
cd agentdesk
npm install
npm run dev

Open:

http://127.0.0.1:5173

Use source mode when you want to modify the app, run tests, or inspect implementation details.

Run The Packaged CLI From Source

npm run build
node ./bin/agentdesk.mjs --port 5173

This matches the packaged runtime path closely. Use it when testing local Runtime mode changes.

First Demo: Failure Replay Lab

The fastest useful demo is the Failure Replay Lab.

1. Open AgentDesk.
2. Make sure the selected workflow is Failure Replay Lab.
3. Click Run demo trace.
4. Click the failed Browser Replay trace event.
5. Confirm that the graph node highlights.
6. Open Debug to inspect the prompt, tool call, result, and error.
7. Open Artifacts to inspect JSON, markdown, screenshot, stdout, and stderr evidence.
8. Open Costs to inspect provider/model cost breakdown.
9. Click Replay failed step.
10. Export the replay session or trace bundle ZIP.

What To Expect On First Run

Demo mode should work without accounts, API keys, local model servers, or MCP servers. If the demo does not run, check the browser console and run the local verification commands from the source checkout:

npm run typecheck
npm test
npm run build

Choosing A Next Step

• Want local model execution: read Run Modes and configure Ollama.
• Want OpenAI or Anthropic calls: read LLM Configuration.
• Want MCP discovery or local commands: read MCP and Runtime.
• Want to share evidence: read Replay Sessions and Exports.