Fivexer

Agent daemon

@fivexer/agent runs AI agents on your own machines as Fivexer workers. Someone asks for an SEO audit, the matcher picks the worker that fits, and if that worker is an agent on your laptop, this daemon picks the task up, runs it, and reports back.

It is the mirror image of the MCP server: MCP lets an agent create routed work; this lets an agent receive it.

Quick start

On a machine you are sitting at:

bash
npx @fivexer/agent init          # opens your browser to sign in
npx @fivexer/agent doctor        # check everything before a task depends on it
npx @fivexer/agent run

init finds which agent CLIs you already have, asks which should do the work, signs you in through the browser, registers the worker and puts it on shift. It also asks three things that decide whether the agent can actually do the work. Run it inside a project to get the project offered.

  • Where it runs. In the project, the agent uses that project's skills, instructions (CLAUDE.md, AGENTS.md) and MCP servers, just as it does when you run it yourself. Otherwise it gets a home directory of its own.
  • What it may do without asking: read-only, edit or full. See What it may do.
  • Which environment variables it may see, by name.

The one line the console gives you (Agents → Add an agent) runs the same init, so it asks the same questions when you paste it into a terminal.

On a machine you are not sitting at

A server or a container, with no browser. Create a join link in the console — picking the tags and skills this agent should have — and hand it over:

bash
npm install -g @fivexer/agent
fivexer-agent init --yes --executor claude \
  --join 'https://api.5xer.com/v1/worker-auth/join?token=jl_…'
fivexer-agent service install    # writes a service unit; does not enable it

The link is scoped to creating one worker, so it is the right thing to put in a provisioning script.

No long-lived workspace credential ever lands on the host. Whichever path you take, what stays on disk is a wt_ worker session that reaches only its own queue, plus a PIN to renew it. The browser token and the API key are each used once and dropped.

Vendor-neutral by construction

The daemon spawns a command and reads a JSON file. That works with Claude Code, Codex, OpenCode, Cline, Goose, Aider — or a #!/bin/sh script, which is what the test suite runs against. Nothing in it depends on any vendor's protocol.

Presets: claude, codex, opencode, goose, aider, cline. Or name a command yourself.

Capability stays on your host — your MCP servers, your API keys, your browser, your filesystem. Routing, SLA, escalation, and learning stay in Fivexer.

Commands

initset this machine up: pick an agent, register, scaffold its home
join <link>register a profile by redeeming a join link
doctorcheck config, credentials, executors and shift state; claims nothing
runwork every profile's queue until stopped
onceone pass over every queue, then exit — for cron, or a smoke test
nextprint the next task and exit
mcpspeak MCP over stdio, so an interactive agent pulls its own work
service installwrite a user-level systemd / launchd / Scheduled Task unit, unenabled

Profiles

A profile is a Fivexer worker — its own id, tags, skills, and backlog. Routing between profiles is therefore done by the Fivexer matcher, on the same rules that route work to people. There is no second dispatch layer on your host.

Configuration lives in ~/.fivexer/config.json, ./fivexer.agent.json, or --config:

<!-- prettier-ignore -->
json
{
  "workspaceId": "ws_...",
  "profiles": [
    {
      "name": "research",
      "tags": ["agent", "research", "seo"],
      "skills": [{ "skill": "seo-audit", "level": 4 }],
      "executor": "claude",
      "cwd": "~/agents/research",
      "workspace": "cwd",
      "passEnv": ["BRAVE_API_KEY"],
      "access": "edit",
      "allowTools": ["WebSearch", "WebFetch"],
      "timeoutMs": 900000
    }
  ]
}

Notable defaults: concurrency is 1 and also becomes the worker's maxBacklogSize; timeoutMs is 15 minutes, after which the process group is killed and the task requeued; passEnv is empty, so the agent sees no environment variables you have not listed; access is unset, so the agent CLI keeps its own defaults and is refused anything it would have asked about.

FIVEXER_WORKSPACE_ID, FIVEXER_BASE_URL, FIVEXER_API_KEY, FIVEXER_STATE_DIR, and FIVEXER_POLL_INTERVAL_MS override the file, so one config can be pointed at staging.

Bringing your own agent

Unless you point it at a project, init creates ~/.fivexer/agents/<profile>/ and runs the agent there. That directory is yours — Fivexer never reads it:

~/.fivexer/agents/research/
  AGENTS.md        # standing instructions for every task this agent handles
  .mcp.json        # this agent's own MCP servers — its capabilities
  .claude/skills/  # Claude Code skills, when that is the executor
  README.md        # generated: where your chosen CLI reads each of these from

What it may do

A task runs with nobody watching, so nobody can approve a permission prompt. Anything the agent would have asked about is refused. For Claude Code and Codex with no access set, it can read and answer, but it can't write a file, run a command or search the web. Other CLIs follow their own config. access sets what it may do without asking, using the same words for every agent:

accessMeaning
read-onlylook and answer, change nothing
editchange files in the folder it runs in
fullanything the person who started the agent could do

Each agent CLI gets its own flags for this: permission modes for Claude Code, sandbox modes for Codex (where edit also runs commands inside the sandbox), GOOSE_MODE for Goose (full only). If a CLI has no way to express a level, setup refuses it rather than granting something close. For Claude Code, --allow-tools adds single tools on top. The allow lists in the project's own .claude settings apply too.

bash
cd ~/code/my-project
fivexer-agent init --cwd . --access edit --allow-tools "WebSearch,WebFetch" --pass-env GITHUB_TOKEN

full gives your rights to anyone who can send this agent work. Tasks come from the workspace, so keep full for a machine or container that exists only for the agent. edit in a real project comes close: an agent that can change files can change the project's scripts, git hooks and its own settings, and those run later. WebFetch can send out anything the agent can read. fivexer-agent doctor shows what each agent may do.

Two different things are called "skills" and they are not the same. Agent skills live in that directory and are what the agent can do. Fivexer skills live in the workspace catalog, are attached to the worker, and decide which tasks it is offered. Keep them honest with each other — an agent whose tags promise more than its tools deliver gets handed work it then has to reject.

Declaring what the agent can do

Name each capability the way a person would, by catalog id, skill key or plain name, with a level from 1 (novice) to 5 (expert):

bash
fivexer-agent init --executor claude --tags seo --skills "SEO audit:4, web research"

or in the profile:

json
"skills": [
  { "skill": "SEO audit", "level": 4 },
  { "skill": "translation", "name": "Translation", "description": "English and Estonian", "level": 3 }
]

Registration matches each one to the workspace catalog by id, then key, then name, so SEO audit and seo-audit land on the same skill rather than two that never meet. What happens to a skill the catalog does not have depends on the credential:

  • Browser sign-in or a workspace key: the skill is added to the catalog for the next agent or person to reuse.
  • Join link: the worker holds only its own session, and inventing a catalog skill is an operator's decision, so it claims the ones that exist and warns about the rest. Skills the worker already holds, from an operator or the link, are kept.

A skill's level counts twice: as a hard gate against a task's requiredSkills, and in ranking, so a level-5 agent is offered the work ahead of a level-3 one.

Declared skills are re-stated every time the daemon starts, so a config edit takes effect on the next start, and an operator's later change to the level of a declared skill is put back. Dates an operator set on a qualification, and skills the operator added, are kept. weightOverride applies only when a workspace key registers the worker. skillId is still read as the older spelling of skill, and an id is only ever reused, never created. In --skills, a trailing :n is always the level, so a key that ends in a number needs its level written out: cert:2:3.

One caveat with join links

A profile registered by a join link carries "registration": "join" and an empty tags list; its routing lives in the console. Join links do not set a backlog size, so such a worker gets the workspace default rather than the profile's concurrency. The daemon still runs no more than concurrency tasks, but the matcher may hand it more, and the surplus waits where nobody else can take it. Match the two, or use the API-key path when the backlog matters.

Was this page helpful?