Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ These are product rules, not implementation details. A change that breaks one ne
- Removing a Service or Project stops it first and deletes its logs. The Project's folder is never touched.

**Coding agents**
- Each app bundles the `localhost` command of its own version. Connect your agents (Settings, the command palette, the first-run empty state) adds a `localhost` MCP server running it, and the localhost-mcp skill, to Claude Code, Cursor and Codex, only at the locations each agent documents.
- Each app bundles the `localhost` command of its own version. Connect your agents (Settings, the command palette, the empty state, the Get started checklist) adds a `localhost` MCP server running it, and the localhost-mcp skill, to Claude Code, Cursor and Codex, only at the locations each agent documents.
- Claude Code's servers change through its `claude mcp` command when it is installed, else by editing `~/.claude.json`. `npx @getlocalhost/cli mcp install` (`packages/cli/`) writes the same entries from a terminal, under the same rules, and Claude Desktop's too; its JSON and TOML editors mirror the core's, so change them together. Cursor reads Claude Code's and Codex's skill folders, so it gets its own copy only when neither has one.
- An update asks before disconnecting connected agents, as it asks before stopping Services; then their `localhost mcp` ends.
- Nothing is written until the user clicks, after seeing the file and the entry. Only localhost's own entries change, the rest of the file byte for byte; each file is backed up before localhost first edits it; Disconnect removes only localhost's entries. A file localhost can't parse is reported, never rewritten.
Expand All @@ -131,6 +131,7 @@ These are product rules, not implementation details. A change that breaks one ne
- Closing the window keeps the app and its Services running; the menu bar or tray shows them. Quitting asks first when anything is active, then stops everything in parallel, whoever started it.
- The apps and `localhost mcp` drive one shared core, so they see the same Runs, on Windows too. When a client disconnects, the core stops the Runs nobody needs any more: none while an app is connected, else those no remaining client started (with their Dependencies). It exits once no client has been connected for 10 s.
- Updates are offered, never installed unasked: a check at launch and every few hours (off in Settings), a notice, then Update Now and Restart to Update. Restarting to update stops every Service first, like quitting, after listing them, and retires the shared core so the new version starts its own. A `.deb` or `.rpm` only links to the release. Builds without the updater's public key never check.
- The first launch of someone new shows a short welcome (Project, Service, Port) ending in Add Project…, then a Get started checklist in the sidebar ticked from real state, until complete or closed. Both are kept in the app's settings, shown once, and never to someone who opened localhost before or already has Projects. Nothing else opens by itself at launch.
- Each active Run is recorded on disk (pid, process group, start time). At the next launch, survivors are offered as Orphans: Stop them (default) or Leave them.

**Machines**
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Shortcuts are written for macOS; on Linux and Windows use Ctrl for ⌘ and Alt f

### 1. Add a Project

Press **⌘N** (or the **+** in the sidebar) and choose your project's folder. localhost fills in a name and a **Key** (a short handle such as `my-saas`, used in logs and by the command line), then scans the folder and lists what it found:
Press **⌘N** (or choose **New Project…** from the **+** in the sidebar) and choose your project's folder. The first time you open localhost, a short welcome explains Projects, Services and Ports and ends here, then a **Get started** checklist in the sidebar follows you to your first running Service. localhost fills in a name and a **Key** (a short handle such as `my-saas`, used in logs and by the command line), then scans the folder and lists what it found:

- **Node**: `package.json` scripts, run with your package manager (`pnpm run dev`, …). Known dev servers get their default port, passed as `$PORT`.
- **Docker Compose**: one `Infra` Service running the whole file (`docker compose up`, in the foreground), or one per Compose service (`docker compose up <service>`) if you'd rather. In the review you can also merge Suggestions into one Service and pick what each starts after.
Expand Down Expand Up @@ -316,7 +316,7 @@ localhost mcp
| Cursor | `~/.cursor/mcp.json` | `~/.cursor/skills/localhost-mcp/`, unless Claude Code's or Codex's folder has it (Cursor reads those too) |
| Codex | `~/.codex/config.toml` | `~/.agents/skills/localhost-mcp/` |

The entry is a server named `localhost` that runs the command bundled with the app (`localhost.app/Contents/Helpers/localhost` on macOS, `localhost.exe` beside the app on Windows, `/usr/bin/localhost` from the `.deb` and `.rpm`, a copy in localhost's data folder for the AppImage) with `mcp`, so the agent always runs the same version as the app. Only localhost's own entry changes: every other server and setting stays as it was. With Claude Code installed, localhost runs `claude mcp add-json` / `claude mcp remove` instead of editing `~/.claude.json` itself. The app opens this screen by itself once, at its first launch. Restart to Update asks before it disconnects connected agents, along with stopping your Services, so the update can replace the command they run. Each file is backed up to `agent-backups/` in localhost's data folder before the first change, connecting again changes nothing, and **Disconnect** removes only localhost's entry and skill. If an agent's `localhost` server runs another command, such as `~/.cargo/bin/localhost`, the app offers **Update**.
The entry is a server named `localhost` that runs the command bundled with the app (`localhost.app/Contents/Helpers/localhost` on macOS, `localhost.exe` beside the app on Windows, `/usr/bin/localhost` from the `.deb` and `.rpm`, a copy in localhost's data folder for the AppImage) with `mcp`, so the agent always runs the same version as the app. Only localhost's own entry changes: every other server and setting stays as it was. With Claude Code installed, localhost runs `claude mcp add-json` / `claude mcp remove` instead of editing `~/.claude.json` itself. After your first Project, the **Get started** checklist in the sidebar offers it too. Restart to Update asks before it disconnects connected agents, along with stopping your Services, so the update can replace the command they run. Each file is backed up to `agent-backups/` in localhost's data folder before the first change, connecting again changes nothing, and **Disconnect** removes only localhost's entry and skill. If an agent's `localhost` server runs another command, such as `~/.cargo/bin/localhost`, the app offers **Update**.

**Or from a terminal**, with the app installed:

Expand Down
8 changes: 0 additions & 8 deletions apps/desktop/src-tauri/src/agents.rs
Original file line number Diff line number Diff line change
Expand Up @@ -76,14 +76,6 @@ async fn blocking<T: Send + 'static>(work: impl FnOnce() -> T + Send + 'static)
tauri::async_runtime::spawn_blocking(work).await.expect("the agents' work doesn't panic")
}

/// Whether Connect your agents should open by itself at this launch: once,
/// the first time localhost runs with it.
#[tauri::command]
#[specta::specta]
pub fn take_connect_agents_offer(state: tauri::State<'_, crate::AppState>) -> bool {
state.settings.take_agents_offer()
}

/// Each agent and where it stands.
#[tauri::command]
#[specta::specta]
Expand Down
3 changes: 2 additions & 1 deletion apps/desktop/src-tauri/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,8 @@ fn specta_builder() -> tauri_specta::Builder<tauri::Wry> {
wsl::wsl_distros,
settings::settings,
settings::save_settings,
settings::onboarding,
settings::save_onboarding,
logs::open_log,
logs::close_log,
logs::clear_logs,
Expand All @@ -171,7 +173,6 @@ fn specta_builder() -> tauri_specta::Builder<tauri::Wry> {
telemetry::set_telemetry_enabled,
telemetry::telemetry_notice_pending,
telemetry::acknowledge_telemetry_notice,
agents::take_connect_agents_offer,
agents::agent_statuses,
agents::connect_agent,
agents::disconnect_agent,
Expand Down
91 changes: 80 additions & 11 deletions apps/desktop/src-tauri/src/settings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,35 @@ struct Stored {
/// Whether closing the window has said that localhost keeps running (`lifecycle`).
#[serde(default)]
has_explained_close: bool,
/// Whether Connect your agents has opened by itself, once, at a launch.
/// Whether Connect your agents opened by itself at a launch, as versions
/// before the welcome did: also a sign the app was opened before.
#[serde(default)]
has_offered_agents: bool,
/// The first-run welcome and checklist; `None` until the first launch
/// that has them decides.
#[serde(default, skip_serializing_if = "Option::is_none")]
onboarding: Option<Onboarding>,
}

/// Where the user is in the first run: whether the welcome was finished
/// or skipped, whether the Get started checklist is over (dismissed,
/// complete, or never shown to someone who used localhost before), and
/// whether a Service has been Running, which the checklist keeps ticked.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "camelCase", default)]
pub struct Onboarding {
pub has_seen_welcome: bool,
pub is_checklist_done: bool,
pub has_started_service: bool,
}

/// What the first run starts from: the saved record, if any, and whether
/// this app was opened before the welcome existed.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Type)]
#[serde(rename_all = "camelCase")]
pub struct OnboardingLaunch {
pub onboarding: Option<Onboarding>,
pub has_opened_before: bool,
}

pub struct SettingsStore {
Expand Down Expand Up @@ -107,18 +133,21 @@ impl SettingsStore {
}
}

/// Whether Connect your agents should open by itself: only the first
/// time this is asked, remembered from then on (for this session only if
/// the file can't be written).
pub fn take_agents_offer(&self) -> bool {
let stored = self.stored.lock().unwrap().clone();
if stored.has_offered_agents {
return false;
pub fn onboarding_launch(&self) -> OnboardingLaunch {
let stored = self.stored.lock().unwrap();
OnboardingLaunch {
onboarding: stored.onboarding,
has_opened_before: stored.has_offered_agents || stored.has_explained_close,
}
if self.write(Stored { has_offered_agents: true, ..stored }).is_err() {
self.stored.lock().unwrap().has_offered_agents = true;
}

/// Remembers the first run's progress; for this session only if the
/// file can't be written, so the welcome never shows twice in one.
pub fn set_onboarding(&self, onboarding: Onboarding) {
let stored = Stored { onboarding: Some(onboarding), ..self.stored.lock().unwrap().clone() };
if self.write(stored).is_err() {
self.stored.lock().unwrap().onboarding = Some(onboarding);
}
true
}

fn write(&self, stored: Stored) -> Result<(), LocalhostError> {
Expand Down Expand Up @@ -164,6 +193,19 @@ pub fn save_settings(state: tauri::State<'_, AppState>, settings: Settings) -> C
Ok(())
}

/// Where the first run stands, and whether localhost was used before it existed.
#[tauri::command]
#[specta::specta]
pub fn onboarding(state: tauri::State<'_, AppState>) -> OnboardingLaunch {
state.settings.onboarding_launch()
}

#[tauri::command]
#[specta::specta]
pub fn save_onboarding(state: tauri::State<'_, AppState>, onboarding: Onboarding) {
state.settings.set_onboarding(onboarding);
}

#[cfg(test)]
mod tests {
use super::*;
Expand Down Expand Up @@ -203,6 +245,33 @@ mod tests {
let _ = std::fs::remove_dir_all(folder);
}

#[test]
fn remembers_the_first_run_and_who_opened_localhost_before_it() {
let folder = std::env::temp_dir().join(format!("localhost-settings-onboarding-{}", std::process::id()));
let path = folder.join("settings.json");
let store = SettingsStore::open(Some(path.clone()));
assert_eq!(store.onboarding_launch(), OnboardingLaunch { onboarding: None, has_opened_before: false });

let onboarding = Onboarding { has_seen_welcome: true, ..Onboarding::default() };
store.set_onboarding(onboarding);
store.save(Settings { log_font_size: 14, ..Settings::default() }).unwrap();
let reopened = SettingsStore::open(Some(path));
assert_eq!(reopened.onboarding_launch().onboarding, Some(onboarding));
assert_eq!(reopened.get().log_font_size, 14);
let _ = std::fs::remove_dir_all(folder);
}

#[test]
fn an_earlier_version_s_file_counts_as_opened_before() {
let folder = std::env::temp_dir().join(format!("localhost-settings-earlier-{}", std::process::id()));
let path = folder.join("settings.json");
std::fs::create_dir_all(&folder).unwrap();
std::fs::write(&path, r#"{"logFontSize":12,"hasOfferedAgents":true}"#).unwrap();
let launch = SettingsStore::open(Some(path)).onboarding_launch();
assert_eq!(launch, OnboardingLaunch { onboarding: None, has_opened_before: true });
let _ = std::fs::remove_dir_all(folder);
}

#[test]
fn missing_fields_take_their_defaults() {
let settings: Settings = serde_json::from_str(r#"{"editorCommand":"zed"}"#).unwrap();
Expand Down
16 changes: 7 additions & 9 deletions apps/desktop/src/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import { startMachines, useMachines } from "./machines";
import { loadHome, tildePath } from "./paths";
import { onPerfMeasurement, runPerfMeasurement } from "./perf";
import { allServices, noService, type ServiceSelection, type SidebarSelection } from "./selection";
import { PROJECT_CONCEPT } from "./onboarding";
import { loadSettings } from "./settings";
import type { CoreView } from "./core";
import type { Navigator } from "./palette";
Expand Down Expand Up @@ -174,9 +175,12 @@ function MainWindow({ view }: { view: CoreView }) {
<section className="emptyColumn" data-column="list">
<EmptyState
icon={<FolderIcon size={40} />}
title="No Projects"
description="Add a project folder to get started."
isStacked
title="Add Your First Project"
description={PROJECT_CONCEPT}
links={[
{ label: "Import Project…", onClick: () => void importProject() },
{ label: "Connect Your Agents…", onClick: () => showSheet({ kind: "connectAgents" }) },
]}
tip={
<KeyTip
before="Press"
Expand All @@ -188,12 +192,6 @@ function MainWindow({ view }: { view: CoreView }) {
<button className="button accent" onClick={() => showSheet({ kind: "addProject" })}>
Add Project…
</button>
<button className="button" onClick={() => void importProject()}>
Import Project…
</button>
<button className="button" onClick={() => showSheet({ kind: "connectAgents" })}>
Connect Your Agents
</button>
</EmptyState>
</section>
<section className="emptyLog" data-column="detail">
Expand Down
8 changes: 6 additions & 2 deletions apps/desktop/src/actions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import {
type Result,
} from "./bindings";
import { listenerKey } from "./listeners";
import { startOnboarding } from "./onboarding";
import { currentCore } from "./store";
import { currentUi, setProgress, setStoppingListener, showAlert, showSheet } from "./ui";

// What the main window's buttons do, on this computer or, given its id,
Expand Down Expand Up @@ -73,15 +75,17 @@ export async function stopListener(details: ListenerDetails) {

/**
* What the user must hear about at launch: unreadable Project files, then
* Orphans. The first launch also opens Connect your agents, once.
* Orphans. The first launch also opens the welcome, once.
*/
export async function runLaunchChecks() {
const result = await commands.launchChecks();
if (result.status === "error") return;
const { unreadableFiles, orphans } = result.data;
if (unreadableFiles.length > 0) showAlert({ kind: "unreadableFiles", files: unreadableFiles });
if (orphans.length > 0 && !isAskingAboutOrphans()) showAlert({ kind: "orphans", orphans });
if (!currentUi().sheet && (await commands.takeConnectAgentsOffer())) showSheet({ kind: "connectAgents" });
const core = currentCore();
if (core.phase !== "ready") return;
if ((await startOnboarding(core.view.projects.length)) && !currentUi().sheet) showSheet({ kind: "welcome" });
}

/** A WSL distro found Orphans as it connected: asks about them, unless the question is already up. */
Expand Down
28 changes: 21 additions & 7 deletions apps/desktop/src/bindings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -473,6 +473,15 @@ async saveSettings(settings: Settings) : Promise<Result<null, CommandError>> {
else return { status: "error", error: e as any };
}
},
/**
* Where the first run stands, and whether localhost was used before it existed.
*/
async onboarding() : Promise<OnboardingLaunch> {
return await TAURI_INVOKE("onboarding");
},
async saveOnboarding(onboarding: Onboarding) : Promise<void> {
await TAURI_INVOKE("save_onboarding", { onboarding });
},
/**
* Streams `source` over `batches`: what is buffered first, then new
* lines; on another Machine (`machine_id`), through its connection.
Expand Down Expand Up @@ -589,13 +598,6 @@ async telemetryNoticePending() : Promise<boolean> {
async acknowledgeTelemetryNotice() : Promise<void> {
await TAURI_INVOKE("acknowledge_telemetry_notice");
},
/**
* Whether Connect your agents should open by itself at this launch: once,
* the first time localhost runs with it.
*/
async takeConnectAgentsOffer() : Promise<boolean> {
return await TAURI_INVOKE("take_connect_agents_offer");
},
/**
* Each agent and where it stands.
*/
Expand Down Expand Up @@ -1360,6 +1362,18 @@ summary: string; isConnected: boolean;
* It waits for the user to connect it again.
*/
needsUser: boolean; projects: Project[]; statuses: StatusView[]; projectStates: ProjectState[] }
/**
* Where the user is in the first run: whether the welcome was finished
* or skipped, whether the Get started checklist is over (dismissed,
* complete, or never shown to someone who used localhost before), and
* whether a Service has been Running, which the checklist keeps ticked.
*/
export type Onboarding = { hasSeenWelcome: boolean; isChecklistDone: boolean; hasStartedService: boolean }
/**
* What the first run starts from: the saved record, if any, and whether
* this app was opened before the welcome existed.
*/
export type OnboardingLaunch = { onboarding: Onboarding | null; hasOpenedBefore: boolean }
/**
* Who or what requested a state-changing action.
*
Expand Down
21 changes: 21 additions & 0 deletions apps/desktop/src/components/EmptyState.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,27 @@
max-width: 220px;
}

/* Quieter actions: a row of links under the main one. */
.links {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 4px 14px;
margin-top: 4px;
}

.link {
padding: 0;
border: none;
background: transparent;
color: var(--accent-text);
font-size: 12px;
}

.link:hover {
text-decoration: underline;
}

.tip {
margin: 4px 0 0;
font-size: 12px;
Expand Down
Loading
Loading