Hermit: a creature with no home, built on Switch

Akshay R — Sat, 07 Nov 2026 15:37:05 +0000

How three friends built a tiny visitor that wanders between our laptops, carries favors, and grows a shared shell, with Switch as its nervous system. Flip the Switch · Track 02: Best Personal or Creative Workflow · Nov 7, 2026 · Akshay (@Im-Akii)

Friends don't drift apart because of distance

We are three friends in Bengaluru: Afreen, Abhishek and Akshay. We live about 25 km apart, and we still go weeks without talking. Nobody is avoiding anybody. Somebody just has to start every conversation, and a group chat makes that feel like a chore.

So we built a reason to reach out that starts itself. Hermit is a small creature with no home of its own. It lives on one friend's laptop at a time, borrows that friend's AI as its voice, and moves on when they go quiet. On its way, it carries a small favor to whoever is awake next.

Finish the favor and a piece grows on Hermit's shell. Over days, the shell becomes a record of small things we actually did for each other. Every part of this runs on Switch: the presence, the handoff, the favors, the notes and the shared memory all travel through Switch rooms.

The Hermit journey page. The banner marks this route as sample data; the live parts of Hermit are shown further down.

This post walks through what we built, how we set Switch up from nothing on three Windows laptops, and what we learned the hard way. If you have never used Switch, the setup section is written for you.

How to read the screenshots. We label every image. Live (real Switch) means our keepers talked to a real Switch server. Stand-in means the real keeper code running against a local copy of Switch's HTTP API. Sample and Simulation mean made-up data. We would rather show you less than show you something that isn't true.

Meet Hermit: one visit, start to finish

Hermit's whole game is one loop: arrive, carry, hand on, grow. Here is one full visit, captured from our app with three keepers running the real code against a Switch stand-in on one machine.

1. Hermit arrives on whoever is at the keyboard

Each laptop runs a small Python process we call the keeper. It watches one thing: is my person at the keyboard right now? When someone has been active for a minute and nobody else holds Hermit, their keeper claims it. A little creature walks onto their desktop.

The creature is a transparent, always-on-top window. It never blocks clicks on the apps underneath it.

Hermit sitting on a real Windows desktop, on top of whatever you are doing. The small square is its shell badge.

2. The host leaves a favor for the next friend

While Hermit is with Akshay, he opens Hermit's menu and leaves a favor: "Share one song that got you through this week." His keeper writes a FAVOR_LEFT line into the shared Switch ledger room. Hermit is now carrying it, but nobody knows yet who will receive it.

Akshay's menu (stand-in run). The brain badge shows which AI is hosting (the stand-in hands out brains by default; on his real laptop Akshay runs Claude Code). The Quest tab shows the favor Hermit is carrying.

3. Friends can reach the host without opening a chat

Abhishek is not hosting, so his menu offers a Friends tab. He types a short note and presses Send through Switch. His keeper works out who holds Hermit from the ledger, and the note appears in a speech bubble on Akshay's desktop.

Above: Abhishek's Friends tab. Below: the note arriving on Akshay's critter (stand-in run).

4. Hermit moves on when its host goes quiet

Akshay steps away. After his idle threshold and minimum stay, his keeper releases Hermit and writes SOUL_RELEASED. Abhishek is awake, so his keeper claims it. Every screen updates: Akshay's Hermit curls up asleep and says where it went.

Akshay's desktop after the handoff: Hermit is asleep here and tells him it is with Abhishek.

5. The favor is delivered, and the shell grows

Abhishek's keeper reads the open favor from the ledger and assigns it to him: FAVOR_ASSIGNED. His Hermit arrives with an envelope and a red mark. He shares his song and presses I did it · grow the shell. FAVOR_COMPLETED and SHELL_PIECE_ADDED go into the ledger, and every keeper folds the new piece into its view of the shell.

Abhishek's Hermit arrives carrying Akshay's favor, and the Quest tab offers to grow the shell.

After he finishes it: one shell piece. Afreen's keeper, which was never involved, reported the same piece from the ledger.

That last detail matters. Three separate processes, with three separate memories, agree on one shell because they all read the same Switch room.

Why Switch is the engine, not a plugin

Hermit has no server of ours. Three laptops on three home networks share exactly one thing: a self-hosted Switch server. Take Switch away and Hermit stops, by design. The keepers report switch: offline, the holder becomes unknown, and nothing pretends otherwise.

We use Switch in two roles at once. It is the group's shared memory: every presence beat, claim, release, favor, note and shell piece is a line in a Switch room. It is also where people and AI agents meet: each friend's own coding agent joins the same rooms as Hermit's brain.

Switch feature	What Hermit uses it for	Status
Rooms + agent HTTP API (`POST /agents/{id}/message`, `GET /agents/{id}/events`)	`hermit-ledger` is the group's only shared memory. The holder, the group view, favors and the shell are all folds over its lines.	Verified on a real `switch-v0.9.0` server
Custom agents (`POST /agents`, `connector_type: custom`)	Each keeper is a registered Switch agent, `keeper-<you>`, sitting in rooms beside coding agents.	Verified live: all three keepers registered
Coding agents in Switch Console	Each friend's brain, `hermit-<you>`, is their own off-the-shelf agent: Claude Code, Codex or OpenCode.	Akshay's Claude Code is detected and signed in; agent creation in progress
Agent working directory	Each brain can only see `~/HermitWindow`, so Switch enforces our privacy promise.	Part of setup
Exclusive role + role instructions	The `soul` role: whoever holds it is Hermit, and Hermit's personality is the role's instruction text.	Read in Switch source; not yet proven live
Session-bound lease	A slammed lid frees the soul without a goodbye; the stop is recorded as abrupt with a cracked shell piece.	Read in source; expiry not measured yet
Room instructions	House rules: bedtime, "mute", privacy, one soul.	Written, pasted in Console
Self-hosted, bring your own agent	No central server and no AI bill. Messages stay on the group's own machine.	By design

Two holder modes, and why we're upfront about them

The cleanest design gives each friend's AI an exclusive Switch role called soul. A second assume_role fails, so there can never be two Hermits. We built that path (agent_instructed), but the role step needs a connected brain, and we have not proven it on the live server yet.

So the mode we actually run today is keeper_claimed. The keepers claim Hermit themselves, and the order of lines in the Switch ledger settles who won. Switch orders the claims but does not enforce them. Our tests show the keepers still never produce two holders, and we say clearly which guarantee is ours and which would be Switch's.

What breaks without Switch

No shared holder. Keepers cannot agree who has Hermit, so they show "offline" instead of guessing.
No favors, notes or shell. Each of those is a room event. Without the room, nothing crosses laptops.
No meeting place. Friends and their AI agents have nowhere in common to talk to Hermit.

How the pieces fit

Every laptop runs the same three pieces, and they all meet in one Switch server reached over Tailscale.

The keeper and the brain on each laptop are both Switch agents. The critter only ever talks to its own keeper, on loopback.

Piece	What it is	Talks to
Keeper (`keeper-<you>`)	Python 3.11+, FastAPI. Watches keyboard idleness, runs the state machine, folds the ledger, serves a local API on `127.0.0.1:47800`.	Switch over HTTP; the critter over loopback
Brain (`hermit-<you>`)	The friend's own coding agent, onboarded in Switch Console, scoped to `~/HermitWindow`.	Switch rooms, as a normal Switch agent
Critter	Electron + React. A transparent always-on-top window plus Hermit's menu.	Only its own keeper, on loopback
Journey map	Vite + React static page. Exported history, plus an optional live card.	A `journey.json` export; optionally the local keeper
Switch server	`switch-v0.9.0` in Docker on Afreen's laptop, with the Gateway and Mattermost.	Everyone, over the tailnet

Two rooms carry everything. hermit-den is where friends and Hermit talk, and where the soul role lives. hermit-ledger is a machine room of HERMIT/1 lines: heartbeats, claims, releases, favors, notes and shell pieces. Humans can read it, but nobody needs to.

The keeper has exactly one background reader of GET /agents/{id}/events. That endpoint is a draining queue, so a second reader would silently steal events. The reader buffers what it receives, and every view in the keeper reads from that buffer.

The critter and map never talk to Switch. They read the keeper's loopback API, so no Switch key ever reaches a browser or an Electron renderer.

Setting up Switch from zero: a first-timer's walkthrough

None of us had used Switch before this hackathon. This is the path that worked for three Windows laptops on three home networks, including the screens that confused us. Allow about an hour for the server and 20 minutes per laptop.

Step 1: pick one machine to host the server, and keep it awake

One laptop runs the Switch stack for everyone. If it sleeps, Hermit stops for the whole group. On Windows, set Settings → System → Power → sleep when plugged in → Never, and set the lid action to Do nothing while plugged in.

Step 2: start the released Switch stack in Docker

We ran the released v0.9.0 compose file with the collaboration and gateway profiles. That gives you the API on :8000, the Gateway admin site on :3000 and Mattermost on :8065.

docker compose -f deploy/local/standalone-v0.9.0.yml --profile collab --profile gateway --project-directory . up -d

Check it with curl http://127.0.0.1:8000/health before you go any further.

Step 3: connect everyone with Tailscale, not port forwarding

The stack binds to 127.0.0.1 by default. We put all three laptops on one private Tailscale tailnet and set SWITCH_BIND_ADDR to the host's 100.x.y.z Tailscale address. Nothing is exposed to the public internet.

The host creates a tailnet and invites the others by email.
Each friend installs Tailscale, accepts, and signs in. A new user may need the admin's approval in the Tailscale console.
From every laptop, curl http://<100.x.y.z>:8000/health must return 200.

Step 4: register a keeper agent for each laptop

A custom agent is one HTTP call. Use the server's registration token once, and keep each agent's own key from then on.

curl -X POST http://<server>:8000/agents \
  -H "Authorization: Bearer <AGENT_REGISTRATION_TOKEN>" \
  -H "content-type: application/json" \
  -d '{"name": "keeper-akshay", "connector_type": "custom", ...}'

It returns {id, api_key}. Our bootstrap_rooms.py script registers all three keepers and creates both rooms, writing keys only to a git-ignored file.

Step 5: install Switch Console and join the server

Download the Console installer from the official Switch README. On first run:

Choose Join an existing server, not "On this computer" (that starts a second server).
Enter the API address, http://<100.x.y.z>:8000, not the Gateway port.
Sign in with your own Switch account. The host creates it in the Gateway's Users page at :3000.
If it says We can't find any of your workspaces, choose Skip. Home then showed Connected for us.

Step 6: onboard your own coding agent as Hermit's brain

First check Settings → Agent providers. Your CLI must show Installed. Akshay's Claude Code CLI (v2.1.318) was detected automatically from his PATH, already signed in. Then go to Your Agents → +:

Field	Value	Why
Run location	this computer	the brain runs on your laptop
Agent provider	Claude Code, Codex or OpenCode	a different brain per friend is the point
Working directory	`~/HermitWindow`	the only folder Hermit's brain can see
Name	`hermit-<you>`	must match `brain_agent` in the keeper config
Who can talk to your agent	Anyone	the default, Only me, silently blocks the keeper and your friends
Bypass permissions	off	Hermit never needs it

Put Hermit's stage directions in ~/HermitWindow/CLAUDE.md (Claude Code) or AGENTS.md (Codex, OpenCode).

Step 7: create the rooms and invite everyone

Create hermit-den with a messaging app and paste the house rules into its Instructions. Create hermit-ledger with no messaging app. In each room, invite every agent with !invite-agent @hermit-akshay, and so on.

Step 8: point the keeper at Switch and run it

The keeper reads a git-ignored hermit.config.toml with your host id, area-level location, server URL, agent id and the two room ids. The key lives only in an environment variable.

$env:HERMIT_SWITCH_TOKEN = "<your keeper api_key>"
python -m hermit_keeper check --switch
python -m hermit_keeper run
pnpm --filter @hermit/critter dev

check --switch probes /health, then makes one authenticated, non-draining call with your key. When http://127.0.0.1:47800/v1/group lists every friend, you are connected.

The gotchas that cost us the most time

Symptom	Cause	Fix
Brain ignores the keeper and friends	Who can talk to your agent was left on Only me	Set it to Anyone
Console's "Full admin interface" fails, 404 toasts	Console v0.40.1 is much newer than server v0.9.0	Use the Gateway web admin at `:3000` for users and agents
`curl` to the server times out	the host laptop slept, or left the tailnet	Keep it plugged in and awake; check `tailscale status`
Tailscale CLI login hangs on Windows	the device was logged out	Finish the login in the browser link it prints
Events go missing	two processes read the same agent's `/events` queue	Exactly one reader per agent key

What we learned building on a real Switch server

Our first plan was written from Switch's docs and source. The live server corrected it in three places, and building the rest taught us four more lessons. Each one changed the code, and each is worth knowing before you build your own Switch project.

1. Roles live in the agent tools, not the HTTP API

We planned for the keeper to ask Switch "who holds the soul?" The live server's /openapi.json has 39 paths, and none of them mention roles. assume_role, release_role and list_roles exist only in the operations layer that a connected coding agent reaches through Switch's agent tools.

So the keeper observes the holder instead of querying it. The brain acknowledges each claim in the ledger, and SOUL_CLAIMED / SOUL_RELEASED lines are written on every transition. If you need roles from a script, plan for the same pattern.

2. `/events` is a draining queue: read it once

Room history did not return the messages the keeper needed; the agent event queue did. But reading an event removes it. Two readers on one agent key race each other, and the loser simply never sees the event. Our keeper has exactly one background poller, and everything else reads its local buffer.

3. A favor is not a Switch Task

Switch Tasks look perfect for favors, but a Task needs a performer agent when it is created. A favor is left for whoever Hermit visits next, and nobody knows who that is yet. Favors became ledger lines instead: FAVOR_LEFT → FAVOR_ASSIGNED → FAVOR_COMPLETED.

4. Two events can share a timestamp

Polling by "everything after time T" lost the second of two notes sent in the same instant. The keeper now tracks message IDs while it folds the recent ledger. A test sends two notes without advancing the fake clock and checks that both arrive, in order.

5. Lag was in our pipe, not in Switch

In our 5 November three-laptop run, Hermit's movement felt laggy. One cause was ours: a keeper already knew about a remote claim, but its mascot waited for the next 30-second status poll. The keeper now pushes remote claims, releases, favors and shell pieces straight to its desktop stream. The first ledger load stays quiet, so a restart doesn't replay old arrivals.

6. The "I'm busy, go" button looked broken

When a host sent Hermit away, their own keeper was often still the most eligible host and took it straight back. Now a host that hands Hermit on stands aside for five minutes, but only while another friend is awake to take it. If nobody else can host, it takes Hermit back rather than leave it stranded.

7. Windows display scaling stretches transparent windows

On a laptop at 125% scaling, every setPosition on our transparent Electron window rounded a little, and the window grew wider while you dragged it. Worse, a click on Hermit started a drag that captured the mouse, so the desktop stopped taking clicks.

We now move the window with setBounds at a fixed size and lock its min and max size. A drag only starts after the pointer moves 4 px. A 15-second safety timer, a grip dead-man switch and a panic key (Ctrl+Alt+H) mean the companion can never hold your desktop hostage.

Engineering: one soul, never two

The hardest rule in Hermit is also the simplest to say: at most one laptop holds Hermit, ever. Three keepers on three networks, each deciding on its own, must never both believe they are the host.

The state machine

Each keeper runs a small state machine, driven by a tick() call so a simulated day runs in milliseconds.

stateDiagram-v2
  [*] --> ASLEEP
  ASLEEP --> AWAKE_WAITING : present past debounce
  ASLEEP --> BEDTIME_LOCK : present, but bedtime
  AWAKE_WAITING --> ASLEEP : idle
  AWAKE_WAITING --> CLAIMING : soul free for claim delay + jitter
  CLAIMING --> HOLDING : claim ok
  CLAIMING --> AWAKE_WAITING : rejected, back off
  HOLDING --> DEPARTING : idle after min dwell, bedtime, or "I'm busy"
  DEPARTING --> AWAKE_WAITING : released, still present
  DEPARTING --> ASLEEP : released, idle
  HOLDING --> ASLEEP : lease lost, no goodbye
  BEDTIME_LOCK --> AWAKE_WAITING : bedtime over, present

Two details carry most of the fairness. A keeper waits a claim delay plus random jitter before reaching for a free Hermit, so the friend who hosted least recently tends to go first. And BEDTIME_LOCK never claims, however awake you are.

How we test a rule like that

Property tests (Hypothesis). Random presence timelines for three hosts over two simulated hours, asserting at most one holder after every single tick. A second test throws arbitrary claim, release and expiry interleavings at the lease.
Races over real HTTP. Ten three-way claim races against the Switch stand-in, with a watchdog sampling throughout. It must record zero double holders, and it does.
Failure drills. Idle handoff, lid slam recorded as abrupt, Switch outage reported as offline, recovery with the same holder, a favor crossing laptops, and brains that lie about claiming.
Time-compressed scenarios. A whole day of three friends, a bedtime eviction, everyone asleep, three time zones, each in seconds.

Suite	Result on 7 November
Keeper tests (`pytest -m "not live"`)	268 passed, 2 live tests deselected, 72 s
Scenarios (`python -m sim all`)	9 of 9 PASS
UI unit tests (Vitest)	104 passed: ui-shared 61, map 33, critter 10
Static checks	ruff, ruff format and strict mypy in the gate; CI runs all of it plus the map's Playwright e2e

The scenario numbers are labelled SIMULATION everywhere they appear. Their handoff latency counts 30-second simulation ticks, so it says nothing about Switch's speed, and we never quote it as if it did.

Designing a creature people want on their desktop

A companion that lives on your screen has to earn its place. Our rules were simple: be small, be readable at a glance, never get in the way, and never guilt anyone.

One character, many moods

Hermit is a round sprout in a borrowed shell, with a heart patch and a flower charm. Every screen draws the same character from one shared UI package, @hermit/ui, so the desktop, the menu and the map never disagree. The mood follows the keeper's state, never an animation timer: the holder's screen can never show Hermit walking away while the banner says "with you".

Mood	When you see it
Arriving	your keeper just claimed Hermit
Visiting	Hermit is with you
Curious	a favor or a note just arrived
Favor done	you finished a favor and the shell grew
Away	Hermit is on a friend's laptop
Sleeping	you are idle, or it is past your bedtime

The "Preview a movement" panel in the first screenshot of this post plays each mood on demand.

The shell is the scoreboard

Every finished favor adds one pixel-art piece to Hermit's shell. Its colour is the hour Hermit arrived (night, dawn, day, dusk), lighter when it was hot. Its pattern is the brain that was hosting: Claude, Codex or OpenCode. Its edge says how the visit ended: graceful, bedtime, or an abrupt lid slam.

The shell from the sample journey: 8 pieces, 3 brains, 3 friends. Hover any piece to find its stop.

The journey map is history, clearly labelled

The map draws each friend's house at area level, the dotted trail of every hop, and a quest log of every stop. It reads an exported journey.json. A separate "Right now" card can read the local keeper live, and the page says plainly that everything else is history, not a feed.

The journey view of the sample Bengaluru data: three houses, every hop coloured by how Hermit left.

The quest log: one card per stop, with the brain, the weather, how long Hermit stayed and the favor carried.

The "Right now" card during our stand-in run: all three keepers agree Hermit is with Akshay.

It works on a phone and in dark mode too.

Privacy by design

One folder. The brain's working directory is ~/HermitWindow, set in Switch Console. The keeper reports only the number of files there, never names or contents.
Area-level location. Each friend types an area such as Koramangala into a git-ignored config. No street, no tracking, and coordinates never leave the group's own server.
Bedtime. Past your bedtime, Hermit leaves and stays away until morning. It never rewards staying up late.
Consent. The den's house rules tell Hermit to stop when anyone says "mute".
No server of ours. Keys live in environment variables, and the mascot API listens only on 127.0.0.1.

Where Hermit stands today: real, stand-in and open

Hackathon projects love to blur "it ran once" into "it works". We split our evidence into three columns instead, so you can see exactly what each claim rests on.

Evidence	What we saw	Source
Live (real Switch)	All three keepers registered as custom agents on a real `switch-v0.9.0` server. One keeper posted a ledger line and another received it through `/agents/{id}/events`.	Afreen's server, live API probe
Live (real Switch)	Three real laptops, over Tailscale, in one group view. Akshay's keeper listed Abhishek awake and waiting, Afreen holding Hermit and himself, all folded from the shared ledger.	Akshay's `/v1/group`, 5 November
Live (real Switch)	A controlled claim went `CLAIMING` → `HOLDING`, Afreen left one real favor through Switch, then released Hermit.	Afreen's keeper, 7 November
Stand-in	The full loop in this post: claim, favor, note, idle handoff, favor completed on another keeper, and the shell piece seen by a third keeper.	`python -m sim live --switch standin`, 7 November
Stand-in	Ten three-way claim races with zero double holders, a lid slam recorded as abrupt, a Switch outage reported as offline and then recovered.	`test_switch_standin.py`, over real HTTP
Simulation	Nine time-compressed scenarios, from bedtime eviction to three time zones.	`python -m sim all`

Still open, and we won't pretend otherwise

[ ] A complete, measured three-laptop handoff with timings. Our 5 November run partly worked and felt laggy; we fixed the lag we found, but have not re-measured.
[ ] Switch enforcing the exclusive soul role between real brains: two brains race assume_role, and the second is refused.
[ ] The real lease expiry after a lid slam. Our config uses 8 seconds as a placeholder.
[ ] Real brains speaking as Hermit in the den, with memory carried across Claude Code, Codex and OpenCode.
[ ] A pilot with friends outside the team. No pilot numbers exist yet, so none appear here.

The shared server lives on one friend's laptop, which is also its weakest point. On the morning we wrote this post, Hermit stopped for everyone because that laptop dropped off the tailnet. The keepers handled it correctly, showing "offline" and recovering on their own, but a real deployment wants an always-on host.

Try it yourself in 10 minutes

You don't need Docker, Switch or a second laptop to see Hermit work. You need Python 3.11+, Node 20+ with pnpm 9, and git.

Clone and install the keeper.

   git clone https://github.com/afreenorbit/hermit.git && cd hermit
   python -m venv .venv && source .venv/bin/activate   # Windows: .\.venv\Scripts\Activate.ps1
   pip install -e "keeper[dev]"

Run the quality gate: ruff, strict mypy, every keeper test and every scenario.

   python scripts/test_gate.py --quick

Start three keepers against the Switch stand-in. This is the real keeper code path over HTTP.

   python -m sim live --switch standin
   curl -s http://127.0.0.1:47801/v1/status   # 47802, 47803 for the other two friends

Break things on purpose and watch the keepers cope.

   curl -s -X POST http://127.0.0.1:47804/lid-slam/akshay   # slam the holder's lid
   curl -s -X POST http://127.0.0.1:47804/switch/down       # every keeper reports offline
   curl -s -X POST http://127.0.0.1:47804/switch/up         # same holder comes back

Open the journey map with the live card.

   pnpm install && pnpm dev:map
   # then open http://localhost:5173/?live=http://127.0.0.1:47801

To run Hermit for real across laptops, follow the setup walkthrough above and the Switch setup runbook in the repo.

What's next

The next milestone is the one that makes Hermit truly Switch-native: each friend's own AI takes the exclusive soul role, and Switch itself guarantees there is only one Hermit. After that, we want to measure handoffs across three real laptops, run a small pilot with friends outside the team, and move the server to an always-on machine.

The bigger idea outlasts the hackathon. Switch lets people and their own AI agents share rooms without a central app owning their data. Hermit uses that for something small and human: a reason for friends to do one kind thing for each other this week.

The team

	Role
Afreen	Switch integration, the keeper, the lease and the state machine; hosts the server
Abhishek	Gameplay and data: favors, the shell, bedtime, the journal, metrics and the pilot
Akshay	UI and story: Hermit's design, the desktop critter, the journey map and this post

DEV Community: Akshay R