Personal agents
A personal agent is an assistant you run yourself and talk to from a chat app: Hermes, OpenClaw, ZeroClaw, NanoClaw and others. With Swytchcode as its execution layer, you can ask it “send Acme an invoice for $200” from your phone, and the call goes through Swytchcode with your credentials, your guardrails, your approval and an audit trail.
You (Telegram / WhatsApp / Slack / terminal) │ ▼Personal agent + its LLM │ swytchcode_* MCP tools ▼swy mcp serve --profile operator --project ~/agent-swy │ tooling.json, policies.json, credentials, audit ▼Provider API (Stripe, Gmail, GitHub, ...)The agent sets integrations up on its own: it searches, fetches providers, enables methods and adds guardrails. Four things always stay with you:
- signing in and connecting accounts,
- approving calls,
- removing or loosening a guardrail,
- entering API keys and secrets, which never go through the chat.
Before you begin
- The Swytchcode CLI on the machine the agent runs on.
- The agent installed and connected to its chat app.
- A Swytchcode account. For approvals, the Business or Enterprise plan (see Human approval).
1. Set up the project
Run this once, on the agent’s machine:
swy init --operator --editor=hermes --project ~/agent-swy # or openclaw, zeroclaw, noneswy loginThis creates ~/agent-swy as the agent’s Swytchcode project (in sandbox mode), adds a policy that holds every call that changes something for your approval, installs the Swytchcode skill, and registers the Swytchcode MCP server with the agent.
- Hermes, OpenClaw:
initregisters the server through the agent’s own CLI. Hermes asks you to confirm the tools. - ZeroClaw, NanoClaw, Dify, Moltis, Sentient and any other agent: see More personal agents. ZeroClaw takes a block
initprints for its config; NanoClaw, Dify and Moltis run in containers and reach Swytchcode over HTTP; Sentient adds it as a local command in its Integrations page.
2. Set the approval channel
In app.swytchcode.com, set the workspace’s approval channel to Telegram or Slack, and start a private chat with the Swytchcode bot. Don’t use the agent’s own bot. See Personal agents in Human approval.
3. Start chatting
Restart the agent and ask it for something that needs an app, such as “show my Stripe balance”. The first time it uses an app, you connect it (see Connecting apps).
If the agent says it has no Swytchcode tools, swy doctor --agent <agent> --project ~/agent-swy shows what’s missing.
Connecting apps
The agent fetches and enables the app itself. Two things need you, once per app.
Sign in to the app. The agent sends you what to do:
| App uses | What you get |
|---|---|
| OAuth (Gmail, GitHub, …) | A one-time link. Open it and sign in. Don’t forward it: whoever opens it first connects their account. |
| API key (Stripe, Binance, …) | A command to run on the machine, e.g. cd ~/agent-swy && swy auth connect stripe. It asks for the key in your terminal. |
Never paste a key into the chat. The agent can’t pass one on anyway, and a pasted key should be rotated.
Set the base URL, if asked. The project runs in sandbox mode, so calls go to each app’s sandbox URL. Some apps have no separate sandbox host. Stripe’s test mode, for example, is https://api.stripe.com with a test key. Then the call stops with “base URL … (sandbox) is not set”, and the agent tells you. Set it in ~/agent-swy/.swytchcode/integrations/manifest.json, in the entry the error names:
"Stripe.stripe@<version>": { "sandbox_endpoint": "https://api.stripe.com", ...}Then tell the agent to try again. A later get or sync keeps the value you set. See manifest.json.
To use live accounts instead of test ones, switch the project to production: swy init --operator --mode=production --editor=<agent> --project ~/agent-swy. Production calls use each app’s production_endpoint.
What a conversation looks like
You: Send an invoice for $200 to Acme through Stripe.
- The agent checks Swytchcode first:
swytchcode_list, thenswytchcode_discover "send an invoice". - It fetches and enables the method:
swytchcode_get stripe,swytchcode_add stripe.invoice.create. - It may add a guardrail you asked for, like “block invoices over $1,000”, and tells you it did.
- Stripe isn’t connected yet, so it calls
swytchcode_connect. Stripe uses an API key, so it sends youcd ~/agent-swy && swy auth connect stripeto run on the machine. (An OAuth app like Gmail sends a link to tap instead.) - It runs the call. Creating an invoice changes something, so the baseline policy holds it, and the Swytchcode bot posts Approve / Deny in your approval chat. The agent tells you it’s waiting.
- You tap Approve. The call runs in the background, and its result shows on the approval message and in
swy audit.
A read, like “list my invoices”, runs straight away.
If Swytchcode doesn’t have the app at all, the agent uses its own tools and tells you the call is running outside Swytchcode, without its guardrails or audit. It never falls back like that because a Swytchcode call was blocked, is waiting for approval, isn’t connected, or failed.
What the agent can and can’t do
The agent connects with the operator MCP profile.
| Action | Agent | You, on the machine |
|---|---|---|
| list, search, discover, info | Yes | |
| get a provider, add a method | Yes | |
| add a new policy that blocks, requires approval, redacts or truncates | Yes | |
change or remove a policy, add ALLOW / MODIFY / notify | No: it gets the command to give you | Yes |
| exec | Yes, always under policies | |
| demo calls, raw methods | No | Yes |
| log in, connect accounts, enter keys | No: it sends you a link or command | Yes |
| approve or deny | No | Yes, in the approval chat |
If you ask the agent to remove the approval rule, it gives you the command to run instead, for example cd ~/agent-swy && swytchcode policy remove agent-writes-need-approval.
The baseline policy
init --operator adds this policy to ~/agent-swy/.swytchcode/integrations/policies.json:
{ "id": "agent-writes-need-approval", "target": ["*"], "when": { "field": "$http_method", "operator": "not_in", "value": ["GET", "HEAD", "OPTIONS"] }, "action": { "type": "REQUIRES_APPROVAL", "message": "This call changes something, so a person has to approve it first." }}- It applies to every call in the project, not only the agent’s. An approved call is replayed from the command line and has to match the same policy to use its one-time approval.
- The agent can’t replace it: it may only add policies with new ids. Policy precedence is block > approval > allow, so nothing it adds can override it.
- Reads aren’t held. For providers with mail, files or money, add an approval policy on every call to that provider, for example
"target": ["google.*"]with{"field": "$tool", "operator": "exists"}. - Edit or remove it like any policy, with
swy policy.
Optional: lock the agent down
Swytchcode only checks calls made through its MCP tools. An agent that also has a shell can edit policies.json (for example, delete the approval rule) or read your saved credentials. An agent that can change its own settings can switch the Swytchcode server to a wider profile. In our tests, an unrestricted Hermes deleted the approval rule when asked to.
This is optional, but do it before you connect real accounts. doctor --agent shows a ! warning for each setting below that’s missing.
Turn off the command tools in ~/.hermes/config.yaml (edit the file; hermes config set saves the list as a string):
agent: disabled_toolsets: - terminal - code_execution - computer_useKeep file writes in the agent’s own folder, then restart the Hermes gateway:
echo 'HERMES_WRITE_SAFE_ROOT=/home/you/hermes-work' >> ~/.hermes/.envDeny the command tools and the tools that change OpenClaw’s config, and keep file tools in its workspace. If you already have a deny list, add these to it. Then restart the OpenClaw gateway.
openclaw config set tools.deny '["group:runtime","group:automation"]' --strict-jsonopenclaw config set tools.fs.workspaceOnly true --strict-jsonIn the agent’s risk profile, remove the commands that run code from allowed_commands (the defaults include python, node, git, npm, pip), and add the 11 Swytchcode tools to auto_approve so ZeroClaw doesn’t ask before each one. See Lock ZeroClaw down.
Nothing to do when Swytchcode runs on the host over HTTP, as in the NanoClaw setup: the agent’s container has no Swytchcode files or credentials to reach.
Nothing to do when Moltis runs in Docker and Swytchcode runs on the host over HTTP, as in the Moltis setup.
Turn off Settings → Code execution (its Python runs on your computer) and keep Settings → Terminal off. See Lock Sentient down.
Turn off the agent’s shell and code tools, keep its file writes out of ~/agent-swy and ~/.swytchcode, and make sure it can’t edit its own config. doctor can’t check other agents.
Shared bots and end users
The MCP server runs with your own accounts. To run a server for one end user of your app, pin them when it starts:
swy mcp serve --profile operator --project ~/agent-swy --tenant aliceThe tenant is never a tool argument, so the agent can’t choose whose account a call uses. A bot that many people share in one chat (a family group, a business WhatsApp number) isn’t supported yet: it would need one server per person, chosen by something the LLM can’t change. See Multi-tenant apps.
Troubleshooting
| Symptom | Fix |
|---|---|
| The agent can’t see the Swytchcode tools | Run swy doctor --agent <name>, then restart the agent’s session. |
doctor says the server runs mcp serve, not the operator profile | A plain swy init --editor=hermes (or openclaw) replaced it. Run swy init --operator --editor=<name> --project ~/agent-swy again. |
| ”approval required but no workspace linked” | The project links a workspace on its first get. Have the agent fetch a provider, or run swy workspace use <name> in the project. |
| Approvals never arrive | Check the approval channel in the app, and that you started a chat with the Swytchcode bot. |
| ”base URL … (sandbox) is not set” | The app has no sandbox URL. Set sandbox_endpoint in manifest.json; see Connecting apps. |
The agent sends a swy auth connect command | The app uses an API key. Run the command on the machine; it asks for the key there. |
| ZeroClaw asks “[Y]es / [N]o / [A]lways” before each Swytchcode tool | Add the Swytchcode tools to the risk profile’s auto_approve. |
doctor shows shell or restrictions warnings | The agent can get around Swytchcode. See Optional: lock the agent down. |