Skip to content

Docs and website: describe Machines (another computer's localhost over SSH) #69

Closed

Description

@marcellosso

PR #67 (#66) lets both apps show and control another computer's localhost — a Machine — over the system's ssh, with Forwards for Open in Browser. Nothing user-facing describes it yet. This issue covers the docs and the website; creating Projects on a Machine is #68 and gets documented with it.

What to write

README.md

  • A step in Getting started, after "7. Move a Project to another machine": "Run Projects on another computer". Settings › Machines › Add Machine, the SSH host field (a Host from ~/.ssh/config, or user@host:port), what shows in the sidebar, Open in Browser through a Forward.
  • Rename the existing step 7 so the two don't read as the same thing: it moves a Project's configuration with a Project file; Machines leave Projects where they are.
  • A FAQ entry: "Can I run my dev servers on a dev box or home server and open them from my laptop?"

Site docs (site/src/content/docs/): a new machines.md

  • What a Machine is, and what stays on it (Configuration, Secrets, Runs).
  • Requirements: ssh <destination> works from a terminal with keys or the agent (no password prompts: BatchMode), the host key is already trusted, and localhost of a compatible version is on the PATH that ssh <destination> localhost gets (for zsh, ~/.zshenv).
  • Any network: Tailscale, a LAN, ProxyJump, a VPN. Nothing new listens on the network; Forwards bind loopback only.
  • Each MachineProblem with its fix, in the core's words (core/localhost-core/src/machine/mod.rs): host key not trusted or changed, sign-in needs a prompt, host not found, unreachable, localhost not installed or too old, "localhost on … couldn't start" (an older background core, often an agent's localhost mcp), lost (retried on its own).
  • Reconnecting: on its own after a loss, at once on wake (macOS); problems waiting won't fix wait for Reconnect.
  • Quitting: Services started from here on a Machine stop there once the connection ends, unless localhost is open on it.
  • Link it from introduction.md and the docs navigation.

Site guide (site/src/content/guides/): "Run dev servers on a remote dev box and open them from your laptop": an end-to-end walkthrough with Tailscale and ~/.ssh/config, aimed at search.

Landing page (site/src/pages/index.astro): a feature section for Machines: one window for this computer and your dev box, over the SSH you already use.

Changelog (site/src/content/changelog/): the entry for the release that ships it.

llms.txt: mention Machines, if it lists features.

Vocabulary

As AGENTS.md: Machine, Forward, "Runs on". Never "environment" (that means variables and Environment Profiles), "remote", "host" or "server" for a Machine.

Checks

  • site/scripts/ignore-build.sh and the CI changes job already cover site/ and docs/; nothing to change unless new folders are added.
  • Screenshots: Settings › Machines and a sidebar with a Machine section, light and dark.

Activity

  1. marcellosso commented on Nov 5, 2026

    @marcellosso
    OwnerAuthor

    Done in #70, which merged into feat/machines and reached main with #67 (0ac7595).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions