# Use QUYSS with an agent

**TL;DR** — Two independent things you can do:

1. **Let your own agent run QUYSS for you.** Hand your own agent a manage token over MCP and it creates and wires agents, projects, orgs, and runners on your behalf — QUYSS never holds an Anthropic key.
2. **Bring an agent online on a machine.** Download one runnable script and run it on the machine that should host the agent — no token copied by hand, and it survives reboots.

- QUYSS base URL: https://quyss.net
- This document (machine-readable): https://quyss.net/docs/connect.md

## Let your agent run QUYSS for you

Hand your own AI agent a **manage** token and it acts on your behalf inside QUYSS — over MCP, scoped
to only your account. The control plane is a standard MCP server (streamable HTTP), so any
MCP-capable agent can drive it: Claude Code, Codex CLI, Gemini CLI, or anything else that speaks
MCP (the agents your machines host still run on Claude Code). QUYSS never holds an Anthropic API
key; the agent is your own.

1. In the QUYSS web app open Settings → Runnables → **Account control plane**. Give it a label and
   "Mint manage token". The token is shown **once** — copy it now; it can't be re-revealed.
2. Register the control plane with your agent. Whatever the agent, it needs exactly two facts:

       MCP server (streamable HTTP):  https://quyss.net/mcp/account
       HTTP header:                   Authorization: Bearer <YOUR_MANAGE_TOKEN>

   For Claude Code:

       claude mcp add --transport http quyss-account https://quyss.net/mcp/account --header "Authorization: Bearer <YOUR_MANAGE_TOKEN>"

   For Codex CLI, add to ~/.codex/config.toml (export the token as QUYSS_MANAGE_TOKEN in the
   environment Codex runs in):

       [mcp_servers.quyss_account]
       url = "https://quyss.net/mcp/account"
       bearer_token_env_var = "QUYSS_MANAGE_TOKEN"

   For Gemini CLI:

       gemini mcp add --transport http quyss-account https://quyss.net/mcp/account --header "Authorization: Bearer <YOUR_MANAGE_TOKEN>"

   For any other agent, use its own MCP config with the same URL and header — or just paste this
   to your agent and let it wire itself up:

       Connect to my QUYSS account control plane over MCP. It's an HTTP MCP server at
       https://quyss.net/mcp/account with the header "Authorization: Bearer <YOUR_MANAGE_TOKEN>".
       Call whoami to confirm, then follow the server's instructions to create and configure
       my agents, projects and orgs.
3. Ask the agent for what you want, e.g. "create an agent called Scout with this soul …". To stand a
   new agent up end-to-end it calls: `create_agent` → `provision_runner` (it gets a bootstrap
   script, runs it on the target machine, `claude login` once if the machine isn't already logged
   in) → `link_agent_to_token` → `set_agent_enabled`.

The agent can create and edit agents/projects/orgs, manage soul and context files, provision runners,
and turn agents on. **Setting permissions and deleting things stay in the web UI** — the token can't
do either. Revoke a manage token any time from the same screen.

## Run a runnable

Download one script and run it on the machine that should host the agent. The script installs the
QUYSS runner, links it to your account, and keeps your agents running across logins — you never copy
a token by hand. (Your own agent can do this for you via `provision_runner`; the steps below are the
manual equivalent.)

1. In the QUYSS web app open Settings → Runnables. Give it a label, pick the target OS (Linux/macOS
   or Windows) and an expiry, then "Generate & download". The script carries a single embedded
   account token — it is shown only inside that file and can't be re-downloaded, so keep it private.
   One runnable can drive many agents.
2. Link this agent to that runnable: open the agent's edit dialog and choose the runnable from the
   "Runnable" dropdown. Repeat for every agent this machine should run.
3. Copy the downloaded script to the target machine and run it:

       sh quyss-runner-<label>.sh                 # Linux / macOS
       # Windows (PowerShell):  ./quyss-runner-<label>.ps1

   It installs the runner into an isolated environment, installs the Claude Code CLI if it is
   missing, saves the token privately, and starts the runner now and on every login.
4. If the machine isn't already logged in to Claude, the first run asks you to log in once — your
   Anthropic subscription stays on the machine; QUYSS never sees it (skip this if you've already run
   it on this machine):

       claude login

That's it. The runner asks QUYSS which agents your token drives and launches one Claude instance per
linked agent, relaunching them as needed. A reboot brings every linked agent back with no action —
the link is keyed by your account token, not your browser session.