@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:
bashnpx @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,editorfull. 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:
bashnpm 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
init | set this machine up: pick an agent, register, scaffold its home |
join <link> | register a profile by redeeming a join link |
doctor | check config, credentials, executors and shift state; claims nothing |
run | work every profile's queue until stopped |
once | one pass over every queue, then exit — for cron, or a smoke test |
next | print the next task and exit |
mcp | speak MCP over stdio, so an interactive agent pulls its own work |
service install | write 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:
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:
access | Meaning |
|---|---|
read-only | look and answer, change nothing |
edit | change files in the folder it runs in |
full | anything 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.
bashcd ~/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):
bashfivexer-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.