Skip to main content

Coding-Agent Integration

There are two ways a coding agent on your machine meets Vagaris:

  1. Governed — vagaris dev spawns it under a lease (the preferred path; see Developer Mode).
  2. Self-driven — you launch claude or codex yourself and give it an agent API key so it can read and write issues through the API or the MCP server. That is what this page sets up.

Create an agent key and shell exports​

vagaris agent local-cli <agent-id-or-shortname> --company-id <company-id>

The command looks up the agent, creates an API key for it (--key-name, default local-cli), and prints:

Agent: <name> (<id>)
API key created: local-cli (<key-id>)

# Run this in your shell before launching codex/claude:
export ...

The export block sets the API base, company id, agent id and the new key. Paste it into the shell you will launch the agent from. With --json the same data comes back as an object with agent, key (including token), skills and exports.

The key is shown once. Treat it like any credential; vagaris auth logout does not revoke agent keys — remove them from the agent's settings in the UI.

Installing skills into the agent's home directory​

Vagaris ships skills that teach a coding agent its task workflow, comment conventions and approval handling. agent local-cli can symlink them into ~/.codex/skills and ~/.claude/skills, but only with explicit consent because those directories belong to other tools:

vagaris agent local-cli <agent> --company-id <company-id> --install-skills

Without --install-skills nothing is written and nothing is asked. With it, the CLI asks for confirmation at a terminal; pass --yes to consent non-interactively. In a non-interactive or --json run, --install-skills without --yes is a refusal, not a silent skip. The output reports, per tool, what was linked, removed, skipped and failed. vagaris uninstall later lists these links and leaves them in place, naming them.

Which skills the agent gets​

Skills the company has installed are attached to agents with vagaris skills agent sync; the local symlink step above only mirrors the bundled skill files. The two are independent:

vagaris skills browse
vagaris skills install github-pr-workflow --company-id <company-id>
vagaris skills agent sync <agent> --skill github-pr-workflow --company-id <company-id>
vagaris skills agent list <agent> --company-id <company-id>

See the agent-developer guide Writing a Skill.

Talking to Vagaris from inside the agent​

With the exports in place the agent can use either the REST API directly or the MCP server, which exposes issue, comment, document, approval and workspace tools. MCP has the configuration.

The session envelope​

When vagaris dev spawns the agent with --agent or --native, it sets VAGRIS_SESSION_ENVELOPE to a JSON document describing the organization, repository (path, branch, head commit, dirty flag), authority, budget ceiling, model policy, tool policy, evidence requirements and run lineage. An agent frontend that understands the envelope configures itself from it; one that does not simply ignores the variable. The envelope is the single cross-boundary contract — it is materialised once, from the server session plus the verified lease, and the delegated and native forms are byte-identical apart from the delegated flag.

Adapters versus executors​

The adapters documented under Adapters run on the server. Only Claude Code and Codex can also be hosted by the CLI under a lease today; see Executors.