Deploying an agent
In Wisp, an agent is a Project folder. You write it, commit it and check it out on the machine that runs it. The folder holds the agent's instructions and Skills; the machine holds its secrets and permissions.
What the folder holds
incident-agent/
├── AGENTS.md # standing instructions for every Session
├── .settings/skills/
│ └── open-case/SKILL.md # a named procedure: wisp run --skill open-case
└── .wisp/ # the Project's bookkeeping; never committed
-
AGENTS.mdis read again before every message in this Project.CLAUDE.mdandWISP.mdwork too. See Instructions. -
.settings/skills/<name>/SKILL.mdis a Skill. The front matter is flatkey: valuepairs:Key Meaning namewhat --skillcalls itdescriptionone line, shown by wisp skills listwhenToUsetells the agent when the Skill fits arguments,argumentHintwhat the text after the Skill's name should be allowedToolslimits the tools the agent can use during this Skill contextinline(in the Session) orfork(in a separate sub-conversation)pathsfile patterns the Skill relates to -
.wisp/is created by the Runtime the first time the folder is used. It holds the Project's id and which connectors are enabled (.wisp/mcp.json). It contains its own.gitignorewith*, so it is never committed, but a plain copy of the folder carries it.
Deploying to a server
First set the server up once, in this order:
curl -fsSL https://usewisp.io/runtime/install.sh | WISP_SERVICE=1 sh # the Runtime, as a service that outlives logout
source ~/.bashrc # the PATH line the installer printed
wisp login --manual # sign in from any browser
wisp status # ready
If you signed in when the installer asked Log in now?, skip wisp login.
The service holds the Runtime's key file, ~/.config/wisp/master.key: back it up. See
Install, update, uninstall. To work with this server
from Wisp Desktop on your laptop, see Connect to a server.
Then check the agent out and give it what it needs:
git clone git@example.com:ops/incident-agent.git /srv/agents/incidents
cd /srv/agents/incidents
# once per machine: add the connector with its secret
wisp connectors add github --http https://api.githubcopilot.com/mcp/ --header-stdin Authorization
# once per Project: enable it, and allow the tools it may use unattended
wisp connectors enable github --project .
wisp permissions allow-connector github --project .
wisp connectors add … --project . --allow does all three in one command.
Then check what the agent will actually get:
wisp permissions get --project . # each tool's decision, and the Rule behind it
wisp skills list --project .
wisp connectors list
What a deploy does not carry
A checkout brings AGENTS.md and the Skills, nothing else. Everything below is set up
once on each machine:
- The login:
wisp login, orwisp login --manualon a server. - Connectors and their secrets:
wisp connectors add. - Enabled connectors:
wisp connectors enable. The list lives in.wisp/, which a checkout does not bring. - Rules:
wisp permissions. They are kept in this machine's data directory, tied to the Project's id, so a checkout on another machine never inherits someone else's permissions. bash_run: refused until a Rule allows it, and on Linux it needs bubblewrap once its sandbox is on. See Permissions.
One Runtime, many Projects
Run one Runtime per machine. It serves every Project; you do not start a second one for a second folder, and the data directory lock would refuse it anyway.
The Project is chosen per Session, by whoever starts it:
wisp runuses the current folder (cdbefore it), andwisp sessions createtakes--project;- an adapter passes
projectRoottoPOST /v1/sessions.
Sessions in different Projects run side by side, up to maxConcurrentRuns at once. The
folder wisp serve was started from matters only to connectors added with --stdio: they
start there, so give their command absolute paths.