Skip to content

docs: connection model documents the machine-global default socket #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arcaven merged 1 commit into from
Aug 2, 2026
Merged

docs: connection model documents the machine-global default socket #103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,14 @@ The `mrvl://` protocol is the primary remote access mode. The daemon runs
its own SSH server, generates its own host key, and manages its own
authorized keys. No dependency on sshd.

The local default is the literal `/tmp/marvel.sock` (`config.DefaultSocket`),
and it is machine-global: no environment variable moves it, and neither does
HOME. A starting daemon unlinks whatever is at its socket path without
checking for a live owner, so a second daemon on that path takes new client
connections while the first keeps running with no reachable path, and either
one's shutdown unlinks the path. Run concurrent daemons on a host with one
`--socket` each, and pass the same value to every client command.

### Cluster configuration

Named clusters are stored in `~/.marvel/config.yaml`:
Expand Down Expand Up @@ -227,13 +235,13 @@ supported mode.
filterable by workspace, team, role, session, and kind, served to
`marvel events`. It carries both control-plane kinds (including
`policy.projected` and `context.limit-unresolved`) and the 12 `agent.*`
kinds. Those twelve are declared
twice under two names: the stream parsers emit the unprefixed vocabulary in
`internal/runtime/events` (`session.started`, `tool.call`, and the rest),
and `internal/session/bridge.go` lifts each one into its `agent.*` ring
kind, which is what lets the daemon and the CLI see one vocabulary
regardless of harness. The ring is bounded, so it is history for the life
of the daemon process, not durable storage.
kinds. Those twelve are declared twice under two names: the stream parsers
emit the unprefixed vocabulary in `internal/runtime/events`
(`session.started`, `tool.call`, and the rest), and
`internal/session/bridge.go` lifts each one into its `agent.*` ring kind,
which is what lets the daemon and the CLI see one vocabulary regardless of
harness. The ring is bounded, so it is history for the life of the daemon
process, not durable storage.

## Manifest formats

Expand Down
Loading