Local, LAN, and Relay editor with eidos serve

eidos serve embeds the same Eidos File editor used by the first-party Web and Lite hosts. It is useful when you want a visual UI while keeping a terminal-owned file workflow.

eidos create tracker.eidos \
  --table Tasks \
  --label-field Title \
  --fields '[{"name":"Title","type":"text"},{"name":"Status","type":"select"}]'

eidos serve tracker.eidos --open

Behavior

• binds to 127.0.0.1 by default;
• uses port 8420 by default;
• opens exactly one file;
• commits editor mutations directly to that file;
• requires no separate Save step;
• ships the UI inside the macOS, Linux, and Windows binaries.

Choose another port when needed:

eidos serve tracker.eidos --port 9000 --open

Explicit assets folder

Serve does not infer or open an assets directory. Mount an existing directory explicitly when the File contains relative entries such as assets/cover.png:

eidos serve tracker.eidos --assets-dir ./assets --open

With the mount active, File fields in the embedded UI can preview images, open or download existing files, and upload files through the picker, drag and drop, or clipboard paste. Uploads are written into the mounted directory with a collision-safe name and the UI persists the resulting assets/<name> File entry through the normal Runtime mutation.

The mounted directory is an explicit capability: without --assets-dir, Serve neither reads nor writes a guessed sibling folder. Relative entries outside the assets/ prefix are not resolved by this mount. Each upload is limited to 256 MiB and previews to 64 MiB. A paired LAN browser, Relay account browser, or guest with a --share link receives the same upload authority for the lifetime of the Serve process, so mount only a directory intended for those users.

Load custom plugins

eidos serve can load .eidos-plugin packages (such as eidos.chart or custom table views) and make them available in the embedded web editor.

# Load a single plugin package
eidos serve tracker.eidos --plugin ./dist/eidos.chart-0.1.0.eidos-plugin --open

# Load multiple plugins
eidos serve tracker.eidos \
  --plugin ./dist/eidos.chart-0.1.0.eidos-plugin \
  --plugin ./dist/eidos.map-0.1.0.eidos-plugin

# Load all plugins from a directory
eidos serve tracker.eidos --plugins-dir ./plugins

If a .eidos/plugins/ directory exists adjacent to the served file, Serve automatically discovers and loads all .eidos-plugin packages within it.

Serve also loads the device-wide store at ~/.eidos/plugins (override with EIDOS_HOME), so plugins installed in Eidos Lite are available here. An adjacent .eidos/plugins/ directory takes precedence, and the strict --publish profile ignores the shared store.

Sandbox and security

Custom views run in an isolated iframe with sandbox="allow-scripts" (without allow-same-origin), assigning each plugin an opaque null origin. Plugins have no access to the host DOM, cookies, local storage, or other plugins.

Each plugin receives a dynamic Content Security Policy (CSP) enforced by the host:

• Outbound network requests are blocked by default, unless exact origins are declared in manifest.browser.networkOrigins.
• Web Workers are blocked unless manifest.browser.workers is set to true.
• Scripts and styles are scoped to the sandboxed document.

Host capabilities

Plugins communicate with Serve via asynchronous JSON-RPC:

• table.read: Retrieves table fields and merged view properties.
• table.page: Fetches paged records respecting active search and filters.
• table.aggregate: Executes high-performance grouped calculations (count, sum, average, min, max) server-side directly in SQLite, without transferring large row datasets over the network.
• table.properties: Persists custom view settings to properties.plugin. In --publish mode, mutations are blocked with a PERMISSION_DENIED error.
• table.openRecord: Opens the record detail panel.
• View settings: If the plugin declares a configuration schema, Serve automatically renders a View settings menu in the table toolbar.

Trusted LAN access

Use --lan to detect and bind one private IPv4 interface:

eidos serve tracker.eidos --lan

The printed URL contains a fragment-only access key. Opening it pairs that browser with the running CLI process; later visits use a process-local, HttpOnly session cookie. If automatic detection picks no suitable address, or the machine has several interfaces, choose an exact private or overlay network address:

eidos serve tracker.eidos --lan --host 192.168.1.20
eidos serve tracker.eidos --lan --host 100.80.12.4

LAN mode accepts RFC 1918, link-local, CGNAT (including typical Tailscale), and IPv6 unique-local addresses. It never accepts a public address or wildcard bind. API Host and Origin must match the selected address exactly.

LAN mode uses plain HTTP. The access link prevents unpaired browsers from using the API, but it does not protect traffic from someone able to observe the local network. Use it only on a private network you trust.

Eidos Relay access

Use --relay when the other device cannot reach the CLI over a private network:

eidos login
eidos whoami
eidos serve tracker.eidos --relay --open

eidos login opens eidos.space for an Authorization Code + PKCE sign-in and stores a renewable CLI session in an owner-only user configuration file. Later Relay commands silently reuse or refresh it without an operating-system credential prompt. eidos logout removes the local credential.

The account session authorizes the CLI to claim your stable opaque r-….eidos.ink hostname. By default, the printed URL contains no access key. Opening it on any device redirects the browser to eidos.space; only the same account that claimed the hostname can complete sign-in. Relay then creates a host-only HttpOnly session for that browser. OAuth tokens never enter the browser URL or the local Serve process.

Use --share only when a guest should be able to open the running file without the owner’s Eidos account:

eidos serve tracker.eidos --relay --share

This explicit share mode prints a fragment-key capability for the current Serve process. Relay exchanges it for an HttpOnly browser session, so the key is not sent in normal HTTP requests. Anyone who receives that link can edit the file while this Relay session remains active.

Starting another Relay serve for the same account takes over the hostname and disconnects the older connector. It also invalidates browser sessions created by the previous claim. Local and --lan use remain account-free. Relay currently accepts request bodies up to 4 MiB, so use localhost or LAN for large CSV imports. --share requires --relay; --relay and --lan are mutually exclusive.

Development UI override

--ui-dir serves a different static build instead of the UI embedded in the binary. This is a developer and release-validation option, not a normal user requirement.

eidos serve tracker.eidos --ui-dir ./dist --port 8420

Concurrency

Multiple localhost, paired LAN, account-authorized Relay, or explicitly shared Relay browsers can edit simultaneously. Serve serializes their mutations through one authoritative Runtime writer and notifies other browsers after every committed revision. A simultaneous stale edit is rejected without side effects and the browser refreshes to the latest revision.

Cell changes and newly appended rows render optimistically. In particular, a new row is editable before its remote insert returns; Serve still commits the row creation before sending edits that depend on its authoritative Row ID.

The Serve process must still be the file’s only physical writer. Stop it before opening the same path in another write-capable host or SQLite tool. After a session, eidos validate tracker.eidos --level full provides an independent integrity check.