octet

Documentation Extensions

Serve

Run the experimental browser interface.

This guide describes experimental Serve in octet 0.8.0. Install the version-matched package, or use a reviewed source checkout:

console
cargo run --features serve -- serve --port 0

A reviewed local package must match the source-built host exactly; see package installation. Catalog installation requires verified matching published assets from the version-pinned release.

This starts a headless host for the launch workspace and opens its local web client. --port 0 requests an available port. Add --no-open to skip opening the browser; --web-root <directory> selects a development asset directory.

The 0.8.0 release notes describe changes and link current signed-asset and public-install evidence. Historical 0.7.6 and 0.7.4 release records retain their signed-asset and public-install evidence; those results do not qualify 0.8.0. Serve remains experimental. Live-provider and native-host audio checks are optional and NOT RUN in this source review. Package smoke does not qualify private-LAN access, actual-terminal/SSH behavior, endurance, or every graphical media, recovery, and visual journey.

Use tasks#

  • Open the app root for a fresh provisional task, an explicit task route to restore that task, or /overview to browse task inventory without creating or opening a task. The overview does not clear an already selected task.
  • Previous, pinned, and running tasks stay in the sidebar. Tasks are independent sessions and can run concurrently; observers of one task share one host owner.
  • Send a prompt, stop a run, steer it, or queue a follow-up. Model and reasoning choices come from the host. Edit, retry, fork, and branch checkout require an idle, committed boundary.
  • Use @ to select trusted project files as explicit context. Use / for host-admitted commands, prompt templates, skills, and enabled extensions. Commands requiring interactive extension confirmation are unavailable.
  • Attach PNG, JPEG, GIF, or WebP images, or bounded text, Markdown, and ordinary PDFs. Model support still governs image input. The production Serve host does not accept audio.

The transcript is the main task view. The command center sorts and searches host-owned task state; sources, changes, outputs, approvals, and progress appear only when structured evidence supports them. There is no extra agent mode or synchronized TUI.

Access and authority#

The host binds IPv4 loopback only. A one-use launch capability is exchanged for an ephemeral HttpOnly, SameSite=Strict browser cookie before API or event-stream access. Host, Origin, and Fetch Metadata checks restrict requests to the local application. Keep the launch capability private.

Browser authentication is not project trust or an agent sandbox. The authority indicator reflects the host's immutable launch policy; per-session changes are unavailable and rejected server-side. Configure restrictions before launch and restart the host to change them. Enabled commands run with the local user's OS authority; use a restricted user, container, VM, or OS sandbox for hostile work.

LAN pairing is not implemented. There is no working --lan, --demo, or --local-only switch. Do not expose this listener through 0.0.0.0, a proxy, or port forwarding. The native companion source is not a supported connection path. In a source checkout, apps/ios/README.md and apps/macos/README.md describe those limitations.

Terminal and recovery#

The terminal appears only when host configuration allows process execution. It starts a local shell in the configured workspace and retains at most four terminals. Browser disconnect or detach retains the shell; host shutdown stops retained shells. Closing an inspector or preview is only a presentation action, not a stop command. Descendant cleanup is bounded, not OS-level process containment.

Reconnect replays missing events or replaces state with an authoritative snapshot on a replay gap. Repeated command IDs do not execute twice. Browser text and attachment drafts are session-scoped and clear after acknowledged submission, but accepted queued follow-ups do not survive a host restart. Conversation checkout and forks do not undo filesystem or other external effects.

Archive and trash retain tasks for later access or restore. Permanent deletion requires the exact confirmation phrase and uses a crash-recovery journal; missing required stores fail before commit. Shared payloads and conversation-content-free inference accounting are retained. See the complete deletion and recovery contract. These are source-described contracts, not a completed current-version recovery qualification.

Install or update a package#

With octet 0.8.0, install or update by name only after matching Serve assets are published and verified on the exact GitHub release. No 0.8.0 publication is claimed by this checkout. Once that gate is met:

console
octet extension install octet-serve
octet extension update octet-serve

For a reviewed matching local archive instead:

console
octet extension install --path ./octet-serve-0.8.0-TARGET.tar.gz
octet extension list
octet serve

Local archive installation does not need GitHub network access. The package requires exactly =0.8.0. Replace TARGET with x86_64-unknown-linux-gnu, x86_64-apple-darwin, or aarch64-apple-darwin; Linux musl is unsupported. A local build/archive is not evidence of signed publication.

Update reinstalls the package matching the running octet version; it is not an independent upgrade to a different runtime version. octet extension remove octet-serve removes package files, not Serve sessions or other user data. See package and release details.

Availability limits#

Production live previews and child-agent trees are disabled. Durable source, diff, and output evidence covers successful built-in read, edit, and write, not all Bash or extension mutations. There is no arbitrary-folder import from the browser, MCP or LSP management, extension catalog/lifecycle UI, scheduling, WAN access, multi-host replication, or hosted account service. Missing capabilities should stay hidden, not appear as empty dashboard sections.

Reference#