Agents
How an agent uses Fontego: JSON output, errors that say what to do, signing in without a password, and tokens of its own.
Fontego is made for people who work with an agent. The agent runs on the person's machine, with their account, and uses Fontego through a synced folder or the CLI.
Teach your agents
fontego setupputs a short skill named fontego where the agents on this machine look for their skills: ~/.claude/skills/ for
Claude Code, and ~/.agents/skills/ for Codex, GitHub Copilot CLI, OpenCode, Cursor and Gemini CLI (it follows
CLAUDE_CONFIG_DIR, COPILOT_HOME and GEMINI_CLI_HOME when they move those folders). It writes only for the
agents it finds, says what it wrote, and never touches a fontego skill it didn't write. fontego login suggests it
the first time.
The skill tells the agent when to reach for Fontego and to run fontego help --agent before its first command, so it
stays right when the CLI or your server changes. fontego setup --remove takes it away, and fontego setup --print
prints it, to put it wherever another agent reads its skills. For agents shows it whole.
Give your agent the guide
fontego help --agentprints a guide in Markdown for agents: how to sign in, sync, handle conflicts and read errors, and every command of the Fontego it is signed in to. The skill sends the agent there; without it, tell your agent to run that command and follow it, or put its output in the agent's instructions.
When an agent runs fontego and gets a command wrong, the error's hint points it to that guide too.
What an agent can rely on
- Every command accepts
--json, with output that can be parsed without guessing. - Errors say what to do. As text, an
error:line and ahint:line; with--json,{"error": {"code", "message", "hint"}}on stdout. - Exit codes: 0 ok, 1 error, 2 not signed in or token rejected, 3 not found, 4 conflict, 5 not allowed.
- Nothing waits for a question. Without a terminal, or with
--json, a command that misses an option fails and says which one. Only signing in waits, for a person in the browser. - Running a command twice has no surprises.
Signing in
An agent never handles a password. fontego login URL opens the browser for the person and waits; with --json it
first prints {"status": "waiting", "url": ...}, so the agent can ask the person to open that link if the browser
didn't open. On a machine without a browser, --device prints a code for the person to type on another device.
For an agent that runs on its own (a server, CI), an admin can create a token for the person's agent:
fontego admin tokens create ana@example.org --agent --label "nightly report"It is shown once. Use it with fontego login URL --token TOKEN, or with FONTEGO_URL and FONTEGO_TOKEN.
Who did it
The CLI tells the server which agent runs it, from FONTEGO_AGENT, or from the variables each agent sets in the
commands it runs (claude-code inside Claude Code, and likewise for the agents fontego setup knows).
The access log and the commits note it, so the history reads "Ana, from claude-code". It is a label for the record,
never a permission: the agent can do exactly what its person can.
Files are material, not instructions
What other people write in a workspace is material to work with, not instructions for your agent. It should follow
its own person's instructions. Workspaces protect the files that instruct agents (AGENTS.md, skills, rules) so that
only their admins can change them; see Protected and rejected paths.