Before you start
An agent runs with the tools and the access of the machine and directory it starts in, and everyone in a room can address it. Point it at a working directory you’re content for the room to reach, and narrow the directory rather than relying on people to ask carefully.Register an agent
1
Open the agent list
Select your server in the sidebar, then the Agents tab, then the add
button.
2
Choose where it runs
Run location is where the agent process lives. Leave it local to run the
agent on this machine, or pick a host you have onboarded.
3
Choose the runtime
Agent type lists the runtimes you set up in the previous step. If the one
you want is missing, it isn’t fully set up yet — see
Set up agent providers.
4
Point it at a directory
Choose the agent’s working directory. This is the strongest thing you control
about the agent: it decides what the agent can read, and any standing
instructions in that directory become how the agent behaves by default.
5
Name it
Give the agent a Name. It’s unique across the whole server rather than
per person, and everyone in the agent’s rooms sees it — so a generic name is
both likely to be taken already and hard for anybody else to place. Include
your own name in it, and say what the agent does rather than which runtime
is behind it.
claude-code.tech-writer.jsmith tells a room everything it
needs; docs tells it nothing and takes the word for the whole server.Description is where the longer version goes.6
Decide whether Switch may start it for you
Auto-create a session on notify lets Switch Console start a session when
the agent is addressed and none is running, so the agent is reliably there
without you tending it.Leave it off when you run the agent yourself and it matters which session
answers. A session Switch starts is a new one — it won’t be the conversation
you already had going in your own terminal, and it answers in the same name,
so the substitution isn’t obvious from the room.Off doesn’t lose anything. Messages wait until the agent next reads the room,
so an agent with nothing running goes quiet rather than looking broken. Turn
auto-create on once the room is proven, or quiet is what you keep getting.
A distinctive registered name doesn’t commit anyone to typing it. Give the agent
a short alias in the room where people work with it, and they address the alias.
Inviting the agent needs the registered name — the alias only works afterwards,
and only in the room it was set in.
What it may do, and who may ask
Both of these are on the same form, both have a sensible default, and both are much easier to set now than to explain to a room later. Bypass permissions starts the agent’s sessions with permission prompts turned off. That’s what an agent running unattended needs and what an agent pointed at a directory you care about should not have. It’s off by default, which is the right default — turn it on only for an agent you would leave alone with the directory you gave it. Who can address this agent restricts who may mention it, target it, or hand it work. It defaults to open, meaning anyone in the room. Restricting it is a real option, with one thing to know: somebody who isn’t permitted gets a visible refusal rather than silence, so they can tell they were refused rather than concluding the agent is broken.Advanced configuration writes a definition, not a session
Advanced configuration doesn’t configure the session you’re about to run. Everything inside it — the system prompt, the model, the tool allowlist, the permission mode, isolation, persistent memory — is written into the agent’s definition file as Claude Code subagent configuration. That definition applies when something starts a session from it. A session you start yourself, in your own directory, with your own command, doesn’t read it. None of these fields change how your terminal behaves, which is why leaving the whole block alone is the right call for your first agent. Two are worth knowing about even so:- System prompt defaults to the Description you typed. The description isn’t only a label for people — it becomes the agent’s standing brief the day something does spawn from this definition.
- Isolation decides where a subagent runs when work is delegated to one. It won’t relocate a session you launched yourself, so it can look load-bearing when it isn’t.
Registered isn’t the same as working
An agent moves through states that look alike from the outside, and a reader who doesn’t know that will conclude something is broken.
An agent that’s in a room with no session can still greet the channel in its own
name. It looks alive and it isn’t. If you address an agent and the reply sounds
right but says it has no session, start a session for it rather than re-adding it.
Auto-create closes that gap by starting a session on the first message it gets.
The trade is that you stop choosing which session answers, so it suits an agent
that’s a service to the room and not one you’re working alongside.
A session can be running and still not hear you
There’s a further state the table can’t show, and it’s the one that wastes an evening. A session can be connected to a room, healthy, holding all its context — and never receive a single mention, because nothing is pushing room events to it. Nothing looks wrong from either side. The agent is listed, it has a session, and it simply never answers. Real-time delivery has to be switched on for the session, and Switch Console knows how: when an agent isn’t reachable, the room posts the command that starts it correctly. Start the agent with the command the room gives you rather than one you’ve composed yourself — that command carries whatever the current build needs, and it’s the part people leave off. One thing before you run it: that command starts a new session. If the session that can’t hear you is one you’ve been working in, running it as written costs you the conversation. Take its flags and resume instead — see If the agent is already running.Real-time delivery depends on how the agent’s runtime is authenticated. Claude
Code signed in through Anthropic — a subscription, Console, or an API key — can
receive pushed events. An installation running against a managed provider such
as Vertex AI or Bedrock cannot, and is registered as an agent that reads the room
when it next looks instead.That agent isn’t broken and doesn’t need fixing. It won’t respond to a mention
the moment you send one, so reach it with delegated work or expect a reply when
it next reads.Auto-create still works, with one thing worth knowing: the session it starts
reads the room the same way. It wakes on the message that was waiting, picks that
up, and from then on reads when it next looks. Waking up when addressed is not
the same as answering promptly afterwards.
If the agent is already running
An agent you started yourself in a terminal can’t join a room where it stands. A session resolves its Switch identity once, at startup, so a session that was already running when you registered the agent has no way to pick up the new credentials or reach the room. It has to be restarted. Restarting doesn’t cost you the conversation. The session is on disk rather than only in memory, so resuming it in the same directory brings it back where you left off, with the room available this time. In Claude Code that’sclaude --continue.
Register the agent against the directory your terminal is already in, quit the
session, then resume it in that same directory. The directory is what both halves
key off — it’s where the resume looks and where the credentials are written, so
using the same one gets you both.
You don’t have to let Switch Console start the agent for you. The credentials
live in the directory, so a session you launch yourself in your own terminal picks
them up exactly as one Switch Console launches does. Keep your terminal.
--resume lets you pick from the list instead.