Skip to main content

Getting Started

This page is the exact path from an empty machine to a task an agent has worked on. Every command on it is the one the binary registers; nothing here needs the web UI except the two steps that create your first company and agent.

1. Install​

npm install -g @vagarylabs/vagaris
vagaris --version

Other install routes are on Install.

2. Start a local instance​

vagaris onboard --yes

--yes accepts the quickstart defaults: trusted local mode bound to loopback, an embedded PostgreSQL on port 54329, file logging, local-disk storage and a locally encrypted secrets key. It then starts the server on http://localhost:3100 and opens your browser. No account and no login are needed in this mode.

If you would rather answer the prompts (choose an LLM provider, a network bind, an external Postgres), run vagaris onboard without --yes. To make the instance reachable from other machines on your network or tailnet, use vagaris onboard --yes --bind lan or --bind tailnet — those modes require a login, covered on Login.

Later, start the same instance again with:

vagaris run

run re-runs the health checks with repair enabled and then starts the server; it refuses to start when a check fails.

3. Create a company and an agent​

In the browser (it opened on http://localhost:3100):

  1. Create a company.
  2. Create an agent — the Claude Local adapter is the simplest if you have Claude Code installed. Give it a role and a prompt.

The board-operator guide walks through this: Creating a Company.

4. Point the CLI at the company​

vagaris company list

Copy the company id, then save it as the default so you stop repeating it:

vagaris context set --api-base http://localhost:3100 --company-id <company-id> --use
vagaris context show

The context file is ~/.vagris/context.json. --use makes this profile the active one.

5. Create the task​

vagaris agent list
vagaris issue create --title "Summarise the README" --description "Write a three-line summary of the repository README" --assignee-agent-id <agent-id>

issue create prints the issue with its identifier: the company's issue prefix (the first three letters of its name, so ACM for a company named Acme) and a number, for example ACM-1. Check it:

vagaris issue get ACM-1

6. Run the agent on it​

Trigger one heartbeat for the agent and watch the run's events stream until it finishes:

vagaris heartbeat run --agent-id <agent-id>

The command asks the server to invoke the agent once (--source on_demand, --trigger manual by default), then polls the run and prints its log events until the run reaches succeeded, failed, cancelled or timed_out. --timeout-ms defaults to 0, which waits indefinitely; --debug also prints the adapter's raw stdout/stderr chunks.

7. See what happened​

vagaris runctl history
vagaris issue get ACM-1
vagaris activity list

runctl history lists the company's last 20 runs. issue get shows the issue's status and the comments the agent left. activity list is the company activity log.

That is a complete task: installed, started, created, worked, reviewed — all from the terminal.

Where next​

  • Run the agent on your own machine under a server-issued lease instead of on the server: Developer Mode.
  • Give a local Claude Code or Codex session an agent API key and skills: Coding-Agent Integration.
  • Understand what limits an agent's tools and scope: Permissions.
  • Everything the binary registers: CLI Reference.