# Features
What each part of the panel does, at whatever length that takes. The README has
the short version; this is where it was moved when that page became a manual.
Links here are relative to `docs/`.
## Sessions
A project is a name and a directory. A new session opens with a chosen way to
start it — a shell in that directory is the first entry, and the rest are launch
profiles. Sessions can be renamed, and a name chosen by hand stops being
overwritten by the pane title. Closing the browser tab does not reach the
session.
Sessions sort by urgency inside their project and can be pinned in place. Each
one can carry scratch terminals, the strip along the bottom of the screenshot;
they open in the same directory, for a `git status` that does not interrupt the
agent above.
A project you are not using can be archived from its row. It leaves the
sidebar, and nothing else happens to it: its sessions keep running and its
notes stay. **Archived · N** under the last project lists them, with a triangle
when a session in one is waiting for you, and the "new project" picker offers
them too — picking an archived project's directory brings it back rather than
adding it twice. Settings → Sessions can archive projects idle for 14 to 90
days; it is off until you turn it on.
## States
Shape carries the meaning as much as colour does.
| | | |
|---|---|---|
| ▲ | **waiting** | the agent stopped and wants a human; sorts first |
| ● | **working** | producing output, or thinking |
| ✓ | **done** | finished, or a shell at its prompt |
A process that is gone gets its own shape: a cross for a non-zero exit with the
status in the label, a hollow square for a clean one, a dashed square when the
tmux session itself has vanished. A live session can be marked *waiting* or
*done* by hand, and stays that way until it does something new.
## State reporting
Left alone, the panel reads the output stream: recent bytes mean *working*, a
terminal bell means *waiting*, a pane back at a shell prompt means *done*. A
silent session is never called finished.
Which means **done is a state the guess cannot reach**. A finished agent has
not exited -- it is sitting at its own prompt waiting for you -- so what the
panel sees is a running process, and the session stays blue until you look. The
first-run tour opens on this for a reason.
**Settings → State reporting** has a button per agent: Claude Code, Codex, Kimi
Code, zcode, opencode and agy (Antigravity CLI). It installs a hook into the agent's own configuration,
showing what it will write and backing up the file first. Each is a different
mechanism in a different file and they fail separately, which is why there is a
row each rather than one "turn reporting on".
The panel knows six and offers three -- Claude Code, Codex and opencode. Tick
the rest below the rows; an agent whose hooks are installed is shown whatever
the ticks say, so nothing you have turned on can be hidden from you. Two of them
have a wrinkle worth knowing: Codex runs a hook only after `/hooks` has trusted
it, and zcode ignores every hook until `hooks.enabled` is `true`, which the
install turns on and only turns back off if it was the one that turned it on. The hook reads two environment
variables the panel injects into each session and posts the state:
```json
{"sessionId": "…", "state": "waiting"}
```
Sessions started outside the panel do not have those variables, so the same
global configuration does nothing for them. Uninstalling removes only the
entries vibepanel added. The hook is a `/bin/sh` script that calls `curl`;
without curl the panel falls back to the heuristic.
Claude Code exposes four events and reports *working*, *waiting* and *done*.
Codex gets the same three through its own hooks, in `~/.codex/hooks.json`
(under `$CODEX_HOME` if that is set): a turn starting or a tool running is
*working*, an approval prompt is *waiting*, a turn ending or being interrupted is
*done*. **Codex runs hooks only once you trust them: after installing, run
`/hooks` in Codex once.** The settings row says whether Codex has recorded that,
and how many running Codex sessions have actually reported. An older install
that used Codex's `notify` line is switched over the next time you press
install.
A Codex session with no hook reporting -- hooks not installed or not yet
trusted, or a Codex too old for them -- is not left to the guess on Linux: the
panel reads the session's own rollout file, which it finds through the files
the pane's `codex` process has open, and takes the turn's start, end and
approval requests from it.
opencode takes a standalone plugin rather than a merge into its configuration, and agy takes a named hook block in `~/.gemini/config/hooks.json`.
Any other agent can report by posting to `/api/hook/state` itself; the shape is
in [docs/api.md](api.md).
## The side panel
Two tabs per project — **Files** and **Notes** — over a dock that is the same on
both. Pressing **Notes** while you are already on it switches to a note that
belongs to no project, and pressing it again goes back. The global one opens
with no project selected, which is where you write down what you are about to
go and do.
- **Files** browses and downloads. Dragging onto the tree or onto the terminal
uploads; the file lands next to the session and its absolute path is typed at
the prompt. Pasting a screenshot into the terminal does the same. Preview
reads a file's magic bytes rather than its name and handles text, PNG, JPEG,
GIF, WebP, AVIF and PDF up to 8 MiB, truncating long text at 256 KiB or 4,000
lines.
An `.html` or `.svg` file is *drawn*, in a frame with an opaque origin, no
scripts and a policy that permits it no network at all, so a page in a project
cannot reach the panel's cookie and cannot fetch anything. **Page** and
**Source** are a two-segment control in the header, and scripts are a per-file
switch that starts off every time.
Above the tree, one line of repository: the branch, how far it is from its
upstream, how much is uncommitted, and a word when there is a conflict.
Pressing it opens the whole thing — the changed files, the last fifteen
commits, and a row per session sitting in a different worktree with its branch
on it, all read off the disk with no credential. One button there asks GitHub
about open pull requests and joins them to those branches by name; it needs
`GITHUB_TOKEN` or `GH_TOKEN` in the panel's environment and runs only when
pressed.
- **Notes** is a markdown pad per project, saved as typing stops.
- **The dock** is the bottom half of both tabs: token usage over the monitor,
in the same place whichever tab is in front. Pressing either opens it into the
side panel, and again into the whole window.
Token usage is what the agents recorded spending — today, this week, this
project, and a split by tool over thirty days. The numbers come from the
transcripts Claude Code and Codex write for themselves. Nothing is estimated
and nothing is priced; where there is no transcript to read the panel shows a
dash rather than a zero.
The monitor is the machine's CPU, memory and disk, and per-session CPU and
memory summed over each session's whole process tree. The percentage is a
share of the machine, not of one core.
## On a phone
A layout of its own: a command composer that gets along with an IME, a soft key
row with `esc` `tab` `ctrl` and the `y`/`n`/`1`/`2` answers agents ask for, and
touch selection with drag handles.
Added to the home screen it is a PWA. Its service worker deliberately caches
nothing: a cached bundle would pin the panel to an old build, and being
restartable underneath a browser is the point of the whole thing.
To hear about a session with the panel closed there is **Settings → Push
notifications**, which POSTs to a URL when a session starts waiting. Bark, ntfy
and ServerChan have presets; anything else is a custom body with `{session}`,
`{state}`, `{project}`, `{url}` and `{time}` in it. Up to twenty destinations,
each of which can be told which states to fire on.
## Launch profiles
**Settings → Launch profiles** names a way to start a session: an argv, and the
environment to start it in. The endpoint is why it exists: the same agent
pointed at Anthropic, at a company proxy and at a self-hosted gateway is three
configurations differing in one variable.
Five ship with the panel: a shell, `claude`, `codex`, `opencode` and `agy`. Those
cannot be edited; a duplicate arrives with the variable names that agent reads
already filled in. A variable left empty is not set at all, so a half-filled
profile runs the agent exactly as a bare terminal would.
There is no "API host" field on purpose. Which variable carries the endpoint is
each agent's decision, and opencode and agy have none. They configure endpoints
and models in their own settings.
A variable can be marked a **secret**, and then its value is never sent back to
a browser: the settings page shows the name and says something is stored. It
reaches the process through tmux rather than a command line, so it is not in
`ps` and not in the audit log. It is **not encrypted**: it is plaintext in the
panel's database file, like everything else there.
A session remembers which profile started it, so a restore after a reboot brings
back the endpoint as well as the command.
## Screens for other people
A **share link** is a URL for a second screen: `https:///share//`.
It opens one **share page** and nothing else: no terminal, no write path, no file
browser, and no way to make a second link from the first.
A share page is HTML, usually written by an agent in one of the panel's own
sessions, reading the panel's data through a small SDK. Everything to do with
it is on the **Sharing** page — its own address, `/sharing`, on the same
sign-in as the panel, and where Settings → Sharing leads — which is one list:
each page, and under it the links that show it.
### Making one, publishing it, handing it out
1. **New page.** Give it a name and pick a starting point — a session wall,
token spend, what got built, a phone glance, or blank — blank really is
blank, and a template is a starting point the agent is free to throw away.
It goes in the pages directory as `page-` unless you give it a
directory, and it becomes a project called `page-lobby`. The pages directory
is `~/.local/share/vibepanel/pages` (the data directory, beside pasted
screenshots) until you change it on the line under the page list; nothing is
stored until you do. With
*start an agent* ticked, an agent opens in it with a first line already typed
at its prompt for you to finish.
2. **Write it.** Above the project's file list, **Share page** opens the Preview
beside the terminal:
- it redraws each time the agent finishes writing a file, on the real data or
on a made-up one — forty sessions, nothing at all, no names, names full of
markup;
- errors the page throws are listed under it, and written to a file the agent
reads;
- **pick** an element and a line pointing at it is typed at the agent's
prompt, for you to finish with what should change;
- side by side on a phone, a laptop and a television, in the window;
- click the preview to open it large over the whole window, switch screens
there, and press Escape to put it away.
From a shell, `vibepanel page check` says what is wrong with a page, file and
line, and `vibepanel page shot` screenshots it on the screens it is for and
reports what broke — which is how an agent checks its own work.
3. **Publish.** From the Preview, from the page's row in settings, or with
`vibepanel page publish` in its directory. Publishing stores the directory as
it is now as the next version; nothing a link shows changes until you do.
4. **New link**, under the page (it needs a published version). Name it, give
the screen a label, choose what it may say and for how long, and set the
page's own settings for this screen. The URL is shown **once** — copy it, or
open it — because the panel keeps only a hash.
5. **Open it on the screen.** That is the whole install.
Afterwards, from the same list:
- **View** (the eye on a link's row) opens what that link is showing right now,
in a new tab, through a fifteen-minute copy of the link. The real address
cannot be shown again, so this is how you look at it.
- **Publish** again and every link following the published version picks it up
on its next poll, without anybody touching the screen. A link can instead be
**pinned** to one version.
- **Try it on a screen** from the Preview puts the draft on one link for ten
minutes; the screen goes back by itself if you do nothing.
- **Versions** lists every published version, and any of them can be rolled
back to.
- **Open** takes you back to the page's project with the Preview beside it. If
its directory has gone — deleted, a new machine, a wiped data directory — the
button says **Restore and open** and writes the published version back first;
if the `page-…` project was removed, it is made again.
**Export** (the download on a page's row) saves the published version as a zip,
or the directory as it is for a page never published; **Import** above the list
makes a new, unpublished page from one. `vibepanel page export` and `vibepanel
page import` do the same from a shell.
If the pages directory cannot be written — a disk that is gone, a data directory
under a system unit's `/var/lib` — new pages go to the next place that works:
`~/.local/share/vibepanel/pages`, then a directory in `/tmp`, and the line under
the list says which and why.
A page can declare settings — a title, a colour, a threshold — that are changed
per link, from the link's row, and reach the screen without a reload. Each row
also says how many screens have the link open right now. **Lock** a link and its
page, version, settings and trials cannot be changed until it is unlocked, which
is what stops the one a customer is watching being changed from a row left open.
Give a link a **remark** — "the screen in meeting room three", "for the
customer" — and it is shown in the settings row and handed to the page. It is
shown in both detail levels, because it is the owner's sentence to whoever is
standing in front of the screen rather than one of the panel's own words.
### What a page can show
The numbers are what the panel knows and what the repositories say, and a page
names which of these it wants in its `vibepanel.json`; nothing else is sent to it.
**What it cost**: what the agents recorded spending, by day, by agent, by model,
by project. Tokens, never money — prices differ by model and tier and change,
and a figure from a stale table is a confident wrong number on a wall.
**What came out**: commits, lines added and removed, files touched — today, over
a window, and as a series. Pull requests open, checks green or red, and what was
merged today, where the panel has been given a GitHub token. These are counted
by reading the working trees, so they are things that exist now and did not this
morning rather than things somebody remembered to tick off. Lines are always two
numbers and never a net one: +1200/−800 is a different day from +400/−0 and the
net figure is the same in both. Work an agent has not committed yet is invisible
to all of it.
**How the day went**: what started, what went quiet waiting for a person, what
finished, and how long things sat before somebody got to them — hour by hour, or
day by day. And a feed of what just happened, which is the thing on a wall that
moves.
Plus the sessions and their states, checklist progress, and the machine's load.
### What a link may say
A link is scoped to the whole panel, one project or one session, and the server
enforces that from the link's own row. Delete the project a link was scoped to
and the link shows nothing, rather than falling back to the whole panel. Detail
is either **counts and states**, the default, which carries shapes and numbers
and no text at all, or **names as well**, which adds session titles and project
names. Neither ever sends a path, a working directory, a command line, a
hostname or the panel's own ids. The name, remark, lock, version and settings
can be changed later; the detail level and the scope cannot, because by then
the URL is in somebody's email and widening what it discloses is a change nobody
holding it would see.
The link is a credential: anyone holding it can watch. Links are revoked
individually, can be given an expiry, and their creation and revocation are in
the audit log. A revoked or expired address answers with a plain page saying the
link no longer works, and nothing of the panel's.
A page runs sandboxed: it cannot read the panel's cookies or storage, call the
panel's API or open its terminal, and cannot reach any other address. The SDK
says *live*, *reconnecting*, *disconnected* or *revoked*, so a page that has
quietly frozen does not look like a quiet machine. [share-pages.md](share-pages.md)
has how.
### Links from before pages
Earlier releases drew **boards** — arrangements of widgets — on share links.
Boards are gone. On the first start after upgrading, every existing link is
pointed at a page made from the template closest to what its board showed (what
got built, token spend, a phone glance, or a session wall), published, in the
same `page-…` directories. The addresses on walls keep working, with the same
detail level, scope, remark and expiry.
## Plugins
Settings → Plugins, or `/plugins`. A plugin is a directory with a
`plugin.json`, or that directory as a zip, and what it does is one or more
rungs of a ladder: a **theme** (a stylesheet of the panel's colour tokens and
nothing else), a **panel** (HTML in a sandboxed frame at a slot), a
**service** (`server.js` inside the panel), a **process** (a command the panel
supervises) or an **unsandboxed** module. The design, the capability table and
what each rung may reach are in [plugins.md](plugins.md); this section is what
you see.
**Arriving is not installing.** *Install from zip* or *From a directory* reads
the plugin by the publish rules and stores it. Nothing runs. What opens is the
install screen: what it is, which rungs, what it may do (one box per
capability, the two that touch a process in red and first), where it reaches
(each host, marked *enforced* or *declared*), what it runs, what it keeps. The
button says *Install* for a theme, *Install and grant* for a panel or service,
*Run this as you* for a process or module. Untick a box and the plugin does not
get that capability; it sees what was granted and degrades. The same screen,
in both languages, is what `vibepanel plugin describe` prints.
**Secrets first.** A plugin that needs a secret (a process's environment, a
secret-typed setting) is installed disabled until every one is set, in the
card's *Settings*. A secret is typed once and never read back; the field says
only whether it is set.
**Settings the panel draws.** A plugin declares its settings as a schema and
the panel draws the form with its own controls, in your language, in the
current theme. A redesign of this page moves nothing a plugin wrote.
**A theme joins the toggle.** An enabled plugin theme is in the cycle of the
theme button on every page (system, light, dark, then each theme), is applied
before first paint on a reload, and recolours the terminal with everything
else, because a theme is the tokens the terminal palette is read from.
**A plugin's panes.** A plugin with a `sidepanel.pane` entry is a third tab
in the side panel's strip, with the icon and title from its manifest, movable
and stackable like Files and Notes; one with a `settings.section` entry is a
block at the end of the settings group it names; a `page` entry is a page of
its own at `/x/`, with the panel's header around it; a `header.item`
is a small box in the panel's header. Each is the plugin's HTML in a sandboxed
frame with no cookie and no storage, holding a grant that reaches that
plugin's own API and nothing else, and it draws the panel through handles:
it never sees a session's id, and never a path unless you ticked that box.
What a frame may ask of the panel is a toast (`ui:notify`), to open a session
(`ui:open`), the panel's own confirm dialog, and its height.
**A plugin's service.** A plugin with a `server.js` runs code inside the
panel: on the events it subscribes to (a session changing state, created or
gone, a project archived, a note or checklist changed), on a schedule, and
when one of its own routes is called -- from its frames, or by you at
`/api/ext//…` with the panel's session or an API token. It may declare
one route the internet can call, behind a secret you store. Each call runs in
a fresh sandbox with a time budget and a cap on what it returns; its `ctx`
has exactly the members of the capabilities you granted, so a script can be
read for what it asks. The card's *Service* block shows its log, how many
events it dropped because it could not keep up, and each source's last fetch.
**A plugin's process.** A plugin with a `process` runs a command the panel
supervises -- a bot, a bridge to somewhere, anything already written in
whatever language -- from the installed version's own directory, with a
cleared environment plus the secrets it named, its own credential in
`VIBEPANEL_PLUGIN_URL` (reaching the plugin API, narrowed to the
capabilities the process declared, and nothing else on the panel) and a
state directory of its own. The install screen shows the exact command and
says *Run this as you*. It is restarted with backoff when it fails and
stopped after ten failures in ten minutes, which the card says; the card's
*Process* block shows what it printed and restarts it. It is ended when the
panel stops. Where the sessions run in a scope of their own, the process
is placed beside them, so a plugin that leaks is measured with the
sessions rather than with the panel.
**An unsandboxed module.** The one rung the panel cannot limit: a plugin's
`main.mjs` loaded on the panel's own page as you, for changing how a piece
of the panel behaves rather than adding beside it. It is off until you turn
on *Allow unsandboxed plugins* on the plugins page, where the red sentence
is; the install screen carries the same paragraph and the button says *Run
this as you*. A module gets a small `host` object -- a stylesheet to inject,
two places to draw into (beside a session's name, in the header), the live
state, the panel's API, a toast, a way to open a session -- and may import
anything else, which is the point and the risk. The card says which panel
versions it was tested on and goes amber outside them. Two ways back that
need no working page: `?safe=1` on the address loads no plugin theme and no
module for that tab, and `vibepanel plugin disable --all` turns every plugin
and the switch off from a shell.
**Dev mode.** A plugin read from a directory has a *Dev* button on its card:
on, the directory's `plugin.json` and files are what runs, under the grants
you already gave that id, and a change to a file reloads every one of its
frames within a second -- an agent in a session beside it edits and sees. Off,
the installed version runs again. A draft asking for a capability you have
not granted runs without it, and the card says so.
**A process on the panel's port.** A plugin's process can be served at
`/api/plugin-http//` instead of opening a port: it listens on a unix
socket the panel names, and the panel does the rest -- who may call (your
sign-in, a *plugin token* you mint on the card per device and revoke one at
a time, or the plugin's declared secret; never nobody), which origins may
call across (your list on the card, exact, Bearer only), the rate limits,
and the cleaning of every response so nothing a process returns can run as
a page on the panel. The process sees none of your credentials, only a
caller name and a per-start secret that proves the request came through
the panel.
**Declared downloads.** A plugin that needs a model or a native runtime
declares it with a hash, and the panel fetches it, follows the release
host's redirects with every hop checked, refuses anything but that hash,
unpacks it safely under the plugin's assets directory and hands the
process the path. A required one is fetched when you enable the plugin and
the process waits for it; an optional one has a *Download* button on the
card, with the size, the host and the progress, and *Remove* takes it away.
**New plugin** is the start of that loop: a name and a template -- `theme`,
`pane`, `service`, `process` or `full` -- and the panel scaffolds the
directory under its data directory (or one you name) with `AGENTS.md`,
`CLAUDE.md`, the SDK and its types, makes it a git repository, registers it
as a project called `plugin-` already in dev mode, and opens the
launch picker for it with the first line typed at the agent's prompt. The
templates are plugins the panel's tests install and run.
**Upgrading** reads a newer version of the same id and draws the screen again
with the boxes as you left them and any new line unticked; the old version
keeps running until you confirm. **Removing** takes the versions, grants,
settings and secrets with it. Everything is in the activity log under
`plugin.`.
From a shell, `vibepanel plugin list | init | check | describe | add |
install --grant … | enable | disable | remove | export | caps` do the same
things with the same words (`init --dev` is the button), and a grant made that way is audited as the user `cli`.
## On a phone, in a chat app
A session that wants you can reach you in Telegram, 飞书 or 微信, and you
answer from the same window. **Messaging** (the link at the bottom of the
settings rail, or `/chat`) is where it is set up, in tabs: channels, people,
rules, alerts, the advanced mode with its key table, and the log.
**Channels.** One card per app. Telegram wants a bot token from @BotFather;
飞书 wants an app's id, secret and verification token, and the card shows the
request URL to paste into the console; 微信 signs in by scanning a QR code.
Every card has a health line that says when a message last arrived, which is
the only thing that tells a working channel from a configured one.
**Privacy.** The chat code connects to nothing until a channel is switched
on: the adapters are written in-house with no SDK and ship in the binary, the
微信 QR code is drawn in your browser, and the screenshot font is bundled. The
first time you switch a channel or the advanced mode on, the panel says what
will pass through outside servers (session titles, what agents say, the
commands they ask to run, screenshots; for the advanced mode, your words and
the session list to the model provider) and goes ahead only once you agree.
The server holds that answer, so an API token cannot skip it either.
**Pairing.** Nobody can talk to the panel until you say so. Whoever messages
the bot first gets a six-digit code and a *pending* row on the page; they tell
you the code and you enter it. A paired person can see and act on every
session. Unblocking someone removes their row, so they pair again with a new
code, and a person can be given a name (微信 gives none). Each person has a mode: *normal* takes commands and
addressed replies, *advanced* also takes sentences.
**What you get.** A card per change, always starting with the session's number:
▲ [3] fix tmux · vibepanel
needs your permission · 2m ago · claude
Bash: go test ./...
On Telegram and 飞书 a permission prompt has *Allow* and *Deny* buttons; on
微信 you reply `y` or `n`. An answer applies to the request you were shown:
a card for a request that has since been answered no longer allows the next
one, and a `y` to a request you never saw shows it to you first. When a
session is working, the card is edited in place rather than sent again where
the app allows it; once a request is answered, its buttons go.
微信 can only answer while you have written recently; what waited while it
could not reach you is shown when you next write.
**Replying.** `3: your words` sends them to session 3; so does quoting its
card. A bare reply goes to the one session that is waiting, and is refused
with the list when two are — a "y" typed into the wrong agent is the one
mistake this cannot make. `focus 3` makes sentences without a number go to 3
even while something else waits (the receipt says who), and `unfocus` clears
it; a bare yes still goes to the one that asked. `3 continue`, `3号 continue`
and `第三个` work too,
and so do voice-note shapes like 「嗯,好的。」. Every delivery comes back as a
receipt naming the number. `help` lists the rest (in Chinese when the bot
speaks Chinese: 列表, 屏幕 3, 停 3): `list`, `screen 3`, `shot 3` (a picture of the
pane), `open 3` (the panel at that session), `context 3` (the last messages,
both sides), `focus 3`, `mute 3 2h`, `stop 3` (asks for `ok` first), `usage`,
`more` (or `more 3` for that session's long message). A picture goes to a
session with its caption, or waits in its input for your next line.
**Rules** decide who is told what: by project, tool, state or message kind,
to everyone or to one person, with quiet hours (a permission request or a
question is never held) and
a screenshot policy. *Preview* picks a session and says which rule would fire
and who would be told.
**Advanced mode** runs a headless Claude Code or Codex on the panel's own
directory. A sentence — "tell the docs one to add a changelog entry", "the one
before last, allow" — becomes an intent, and anything that writes waits for
your `ok`. `ask: what is 3 doing` answers from read-only tools. 微信 voice notes
arrive transcribed; the agent never sees a pane's output when deciding where
to send anything. There is a daily budget, and the page shows today's spend.
**Questions with options.** When Claude Code asks with a menu, questions
with options or a plan to approve, the card is the question and its options,
never allow and deny. Reply a number to choose, `1 3` for several, or write
your own answer; `2, extra words` chooses with words attached; `skip` leaves
it. Several questions are asked one after another and submitted together at
the end. A plan takes `1` (go ahead), `2` (go ahead, approving edits) or
whatever you want changed. Telegram and 飞书 cards have a button per option.
**The machine.** `system` (「系统」, 「监控」) answers with CPU and load, memory,
swap, disk, uptime and the sessions using the most. **Alerts** message you when
CPU stays above a threshold for a while (90% for ten minutes by default), or
memory or disk use passes theirs (90%, 95%), naming the session using the most,
and again when it recovers; a machine sitting on the line is one alert, not one
a minute. Thresholds and who is told are on the Alerts tab; 「静音告警 1小时」
(`mute alerts 1h`) pauses them for you and 「恢复告警」 turns them back on. They
go only through channels already switched on. In the advanced mode, `ask: how
is the machine` reads the same numbers.
**Keys** is what "allow" presses per tool. Claude Code takes Enter, Codex takes
`y`; the others copy Claude Code and are editable. A key must be one tmux
knows, and *Reset to defaults* puts the table back.
Nothing here is a group: every conversation is one person, one bot.
## The first run
A panel with no account prints a one-time token; you paste it, choose a
password, and the tour opens.
Five steps, and two of them do something. It installs state reporting for the
agents the panel is set up for -- separate mechanisms in separate files, a
button and an answer each -- and it offers the rest of Claude Code's settings: session mirroring,
Remote Control, the commit and pull-request attribution, the billing header.
Every key is printed with the value on disk beside the value that would replace
it, and the file is copied before anything is written.
It is put away for good on the server rather than in the browser, so reading it
on a laptop settles it for the phone as well.
## Restarts, reboots and upgrades
```sh
systemctl --user restart vibepanel # the panel goes away and comes back
tmux -L vibepanel ls # every session still there, still running
```
The panel attaches to tmux as a client and never owns a session's terminal, and
it runs on its own socket (`-L vibepanel`) with its own config, so it sits
beside an existing tmux or zellij setup. Browsers with the panel open notice the
new build on reconnect and offer to reload.
A reboot is different. The tmux server is an ordinary process and its scrollback
lives in that process's memory, so the machine going down takes both.
The panel keeps what it needs to rebuild each session: the command it was
created with, its directory, its name and place, and the last 2,000 lines or 256
KiB of its scrollback, captured every thirty seconds and again at shutdown. An
orderly reboot loses no output; a power cut loses up to half a minute. On the
next start the panel offers to restore them, one or all, showing the command
each will run and where. A per-session switch restores without asking; it is off
by default.
The **processes** do not come back. An agent's context lived in its process and
in a conversation with a provider, and re-running the command starts a new agent
that remembers none of it. The restored pane says so in a banner, and the
session keeps a `restored` mark.
**Settings → Updates** fetches the newest release from GitHub, verifies it
against the published `SHA256SUMS`, runs the new binary once to see that it
starts on this machine, swaps it in and restarts the service, keeping the old
one as `.old`. The download runs on the server, so a tab that sleeps or reloads
mid-way comes back to the same progress bar; the release notes are shown before
you agree to anything, and the sidebar says when a release is waiting.
The panel checks on its own, and only while somebody has it open: when the last
answer is more than six hours old, one request to `api.github.com` carrying
nothing but the version number. There is no timer, no heartbeat and no
telemetry; a panel nobody opens never asks. The check can be switched off in
the same section, and the button works either way.
It talks to `api.github.com` and has no mirror setting, so a machine that cannot
reach GitHub takes the other route: unpack a new archive and run
`./deploy/install.sh` again, which keeps the existing unit and restarts it.
Either way the sessions keep running.
Two behaviours worth knowing: a changed tmux config takes effect at the next
`start-server`, and the panel never kills its server, so the settings page and
`vibepanel doctor` report when the file on disk and the settings in memory have
diverged; and an older binary refuses a database a newer one has migrated,
naming both versions rather than opening it and dropping columns.
[docs/runbook.md](runbook.md) is organised by symptom for everything else.
## Settings that live in a file
**Settings → This panel** edits the service's environment file: the address,
the domain, TLS and its certificates, ACME, and who is allowed to reach the
panel at all. It writes the same file the installer wrote, keeping every
comment and commented-out example where it was, and copies it first.
These take effect on the next start, so the restart button is the next block
down. It stops the panel and lets the service manager bring a new one back --
which costs the connection and nothing else, because tmux owns the sessions. On
a machine where nothing would restart it, the button says so instead of
stopping.
Two settings are shown and not editable. `CLOUDFLARE_API_TOKEN` is a
credential, so the page never receives it. `VIBEPANEL_TMUX_SOCKET` is the one
that keeps the panel away from your own tmux: a panel pointed somewhere else
cannot see its own sessions, and the ones it was managing keep running with
nothing attached to them.
## On a network
The panel listens on `:18443`, on every interface, and is built to face the
public internet.
Everything needs a credential, including the WebSocket, which is the terminal.
The exceptions are the health probe, the hook endpoint (which takes a token
injected into every session) and the share link (which takes a share token, on
its page's files and its snapshot — `GET`s only — and is rejected
everywhere else).
First run prints a one-time setup token to the console: whoever can read the
server's output claims the panel, and the endpoint closes once an account
exists. Failed logins back off exponentially per source address, and
`--allow-from` limits who can reach the panel at all. Both judge the address
that `--trusted-proxies` says to trust; with none configured that is the peer on
the socket, and `X-Forwarded-For` is ignored.
**Passkeys** sit on top of the password and never replace it. WebAuthn needs a
registrable domain name, so an IP address can never register one however the TLS
is arranged. `vibepanel doctor` and the sign-in screen both report whether the
current configuration supports them.
**API tokens** are independent of the password: changing the password signs out
browsers and leaves tokens alone, and the reverse. A token is readable once,
when it is created.
**TLS** is the panel's own, either supplied or issued:
```sh
# your own certificate, reloaded when the files change
vibepanel --domain panel.example.com --tls files \
--tls-cert /etc/ssl/panel.pem --tls-key /etc/ssl/panel.key
# or issued and renewed automatically
CLOUDFLARE_API_TOKEN=… vibepanel --domain panel.example.com \
--tls acme --acme-dns cloudflare --acme-email you@example.com
```
Automatic certificates use DNS-01, since HTTP-01 needs port 80. Cloudflare is
the provider that is wired up. Leaving TLS off anywhere but loopback is warned
about at startup.