Quickstart: local runtime

This runs entirely on your machine. No account, no repo connection, no network dependency on Ravel.

Install

npm i -g @runravel/ravel

Requires Node.js 22+.

Scaffold a team

ravel create my-team

This creates a starter team: a root agent.md, one subordinate agent with its own tools.json, a processes/hello.process.md, and a package.json that depends on @runravel/ravel.

Validate it

cd my-team
ravel validate

Validation compiles the folder tree against the config schema and prints any errors (✗) or warnings (⚠) — this is the same check the platform runs before a deploy activates, so if it’s clean here, it’s clean there.

Run a process

ravel run hello

Boots the team, runs the hello process to completion, prints the result, and exits. Useful flags:

• --input key=value — pass input to the process (repeatable)
• --dry-run — run without executing real tool handlers
• --sync — block for a y/N approval instead of queuing an async proposal

Talk to one agent directly

ravel chat "" "What can you help me with?"

"" addresses the root agent; a path like growth/copywriter addresses a subordinate. This bypasses the orchestrator — useful for poking at one agent without running a full process.

Run it as a live service

ravel serve

Boots the team and keeps it running: an HTTP + SSE API and a local operator console on one port (default 4317), bound to 127.0.0.1 only — the API has no authentication by design, since it’s meant for local use. Open http://localhost:4317 to watch runs, approve proposals, and inspect state as they happen.

For iterating on a team’s config without the server, ravel watch boots the team and hot-reloads on file changes — no HTTP server, just a fast local loop.

Next

Once a team runs the way you want locally, connect the same repo to the platform to run it in production.