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 provides a visual UI while keeping a terminal-owned file workflow.

eidos file new 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 open an assets directory automatically. 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. They can open or download existing files, and upload files through the picker, drag and drop, or clipboard paste. The server writes uploads into the mounted directory with a collision-safe name. The UI saves the resulting assets/<name> File entry through the normal Runtime mutation.

The mounted directory is an explicit capability. Without --assets-dir, Serve does not read or write a sibling folder. Relative entries outside the assets/ prefix are not resolved by this mount. The server limits each upload 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. Mount only a directory intended for those users.

Load custom plugins

eidos serve can load .eidos-plugin packages 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 next to the served file, Serve automatically finds and loads all .eidos-plugin packages within it.

Serve also loads the device store at ~/.eidos/plugins. You can override this path with EIDOS_HOME. Plugins installed in Eidos Lite are available here. An adjacent .eidos/plugins/ directory takes precedence. The strict --publish profile ignores the shared store.

Sandbox and security

Custom views run in an isolated iframe with sandbox="allow-scripts". The host assigns each plugin an opaque null origin. Plugins cannot access the host DOM, cookies, local storage, or other plugins.

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

• The host blocks outbound network requests by default. You can declare exact origins in manifest.browser.networkOrigins.
• The host blocks Web Workers unless you set manifest.browser.workers to true.
• The browser limits scripts and styles to the sandboxed document.

Host capabilities

Plugins communicate with Serve via asynchronous JSON-RPC:

• table.read: Reads table fields and merged view properties.
• table.page: Reads paged records with active search and filters.
• table.aggregate: Calculates grouped indicators in SQLite directly, without transferring large row datasets over the network.
• table.properties: Saves custom view settings to properties.plugin. In --publish mode, the server rejects mutations with a PERMISSION_DENIED error.
• table.openRecord: Opens the record detail panel.
• View settings: When the plugin declares a configuration schema, Serve renders a View settings menu in the table toolbar.

Trusted LAN access

Use --lan to find 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 finds no suitable address, or the machine has several interfaces, specify 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, and IPv6 unique-local addresses. It rejects public addresses and wildcard binds. 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 observers on the local network. Use it only on a private network that 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 and PKCE sign-in. It stores a renewable CLI session in an owner-only configuration file. Later Relay commands reuse or refresh it without an operating-system prompt. eidos logout deletes 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 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 must open the running file without the owner 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 does not travel 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 accepts request bodies up to 4 MiB. 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 option supports development and release validation.

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

Concurrency

Multiple localhost, paired LAN, account-authorized Relay, or explicitly shared Relay browsers can edit at the same time. Serve serializes mutations through one authoritative Runtime writer and notifies other browsers after every committed revision. The server rejects a simultaneous stale edit without side effects. The browser then 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 commits the row creation before sending edits that depend on its authoritative Row ID.

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