feat(server): vana server start runs in the background by default (#63)

* feat(server): vana server start runs in the background by default

`vana login` already started the server in the background while `vana
server start` stayed in the terminal, so the same action behaved two ways.
Now both run in the background, return once the server answers, and
`vana server stop` stops it. --foreground keeps it in the terminal with its
logs (debugging, containers, a service manager); --detach is still accepted.
The background process itself runs --foreground so it never detaches again.
README and the agent-access skill describe the new default and the public
server, not the old --public flag.

Claude-Session: https://claude.ai/code/session_01Fcv6uEy4zcXaigzDNxeW3j

* docs(server): describe server start as running in the background

Claude-Session: https://claude.ai/code/session_01Fcv6uEy4zcXaigzDNxeW3j

Author: volod-vana

README.md

@@ -40,14 +40,14 @@ vana login                  # Vana account, or --server <url> for a self-hosted
 vana connect github         # managed browser, collects, syncs to your server
 vana data show github       # what was collected
 vana server status          # your server, local and registered URLs
-vana server start           # run your own server here when Vana Desktop is not
+vana server start           # run your own server in the background (no Desktop needed)
 ```
 
-`vana server start` is local only: `vana connect` writes to it, apps cannot
-reach it. `vana server start --public` registers it on-chain for your
-account, opens a public URL through Vana's relay, syncs to Vana storage, and
-stays public on every later start. A registration cannot be removed, so this
-is a step you take on purpose. On a Mac the tunnel client is a build of frpc
+`vana server start` runs your Personal Server in the background and returns
+once it answers; `vana server stop` stops it, and `--foreground` keeps it in
+the terminal with its logs. It is public by default: registered on-chain for
+your account, reachable through Vana's relay, and synced to Vana storage.
+`--local` keeps it on this machine only. On a Mac the tunnel client is a build of frpc
 signed and notarized by Vana (or Vana Desktop's copy, when installed).
 
 **Builder side** is what an app or an agent uses to work with someone

skills/agent-access/SKILL.md

@@ -79,7 +79,7 @@ On the owner's machine:
 npm install -g vana-cli             # or: npx vana-cli <command>
 vana login
 vana connect github                 # or any source from `vana sources`
-vana server start --detach
+vana server start
 vana server status --json
 ```
 
@@ -94,7 +94,7 @@ by an earlier `vana` and must be restarted, do it:
 
 ```bash
 vana server stop
-vana server start --detach
+vana server start
 ```
 
 ## 2. Install the agent and load the builder skill

src/cli/index.ts

@@ -693,7 +693,7 @@ Examples:
 Examples:
   vana server
   vana server start
-  vana server start --detach
+  vana server start --foreground
   vana server stop
   vana server set-url http://localhost:8080
   vana server set-url https://ps-abc123.server.vana.org
@@ -746,7 +746,7 @@ Examples:
   server
     .command("start")
     .description(
-      "Run your own Personal Server here, in the foreground, when Vana Desktop is not running one",
+      "Run your own Personal Server in the background (no Vana Desktop needed); stop with `vana server stop`",
     )
     .option(
       "--port <port>",
@@ -756,36 +756,48 @@ Examples:
       "--local",
       "Stay local only: no public URL, no on-chain registration, apps cannot reach it",
     )
-    .option("--detach", "Run in the background; stop with `vana server stop`")
+    .option(
+      "--foreground",
+      "Stay in this terminal with the server's logs; stop with Ctrl+C",
+    )
+    .option("--detach", "Run in the background (the default)")
     .option("--json", "Output machine-readable JSON")
-    .action(async (startOptions: { port?: string; local?: boolean }) => {
-      process.exitCode = await runCommandWithTelemetry(
-        { ...telemetryBaseContext, command: "server", subcommand: "start" },
-        async () => {
-          const port = startOptions.port
-            ? Number(startOptions.port)
-            : undefined;
-          if (
-            port !== undefined &&
-            !(Number.isInteger(port) && port > 0 && port < 65535)
-          ) {
-            process.stderr.write("--port needs a port number.\n");
-            return CliExitCode.USAGE;
-          }
-          return runServerStart(
-            {
-              network: resolveNetwork(parsedOptions.network).name,
-              port,
-              noInput: parsedOptions.noInput,
-              yes: parsedOptions.yes,
-              local: startOptions.local,
-              detach: parsedOptions.detach,
-            },
-            serverStartIo(parsedOptions),
-          );
-        },
-      );
-    });
+    .action(
+      async (startOptions: {
+        port?: string;
+        local?: boolean;
+        foreground?: boolean;
+      }) => {
+        process.exitCode = await runCommandWithTelemetry(
+          { ...telemetryBaseContext, command: "server", subcommand: "start" },
+          async () => {
+            const port = startOptions.port
+              ? Number(startOptions.port)
+              : undefined;
+            if (
+              port !== undefined &&
+              !(Number.isInteger(port) && port > 0 && port < 65535)
+            ) {
+              process.stderr.write("--port needs a port number.\n");
+              return CliExitCode.USAGE;
+            }
+            return runServerStart(
+              {
+                network: resolveNetwork(parsedOptions.network).name,
+                port,
+                noInput: parsedOptions.noInput,
+                yes: parsedOptions.yes,
+                local: startOptions.local,
+                // In the background unless asked to stay: `vana login` starts
+                // it that way too, and the server outlives the terminal.
+                detach: !startOptions.foreground,
+              },
+              serverStartIo(parsedOptions),
+            );
+          },
+        );
+      },
+    );
 
   server
     .command("stop")
@@ -2972,7 +2984,7 @@ async function runServerStatus(
 
   if (target.state !== "available") {
     emit.blank();
-    emit.next("vana server start --detach");
+    emit.next("vana server start");
   }
 
   emit.blank();
@@ -7132,7 +7144,7 @@ async function runLogin(
             renderer.detail(`Personal Server: ${running} (running)`);
           } else {
             renderer.detail("No Personal Server found for this account yet.");
-            renderer.next("vana server start --detach");
+            renderer.next("vana server start");
             renderer.detail(
               "Or point at one you already run: vana server set-url <url>",
             );
@@ -7256,9 +7268,7 @@ async function offerServerStart(
     ...vanaPromptTheme,
   });
   if (!start) {
-    process.stderr.write(
-      "  Start it later with `vana server start --detach`.\n",
-    );
+    process.stderr.write("  Start it later with `vana server start`.\n");
     return;
   }
   await runServerStart(

src/personal-server/local/detach.ts

@@ -71,6 +71,9 @@ export async function startDetachedServer(input: {
       process.argv[1],
       "server",
       "start",
+      // The background process is the server itself; without this it would
+      // detach again.
+      "--foreground",
       "--json",
       "--no-input",
       "--yes",