gitspace 0.2.0-rc.2 → 0.2.0-rc.4

package/.claude/settings.local.json

@@ -15,7 +15,11 @@
       "Bash(xxd:*)",
       "WebFetch(domain:ast-grep.github.io)",
       "WebFetch(domain:developers.cloudflare.com)",
-      "WebFetch(domain:gitspace.sh)"
+      "WebFetch(domain:gitspace.sh)",
+      "Bash(/Users/bradleat/spaces/spaces/workspaces/remote-space/dist/gssh-darwin-arm64:*)",
+      "Bash(npx wrangler pages deploy:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
     ]
   }
 }

package/AGENTS.md

@@ -215,10 +215,11 @@ src/
 | Command | Description |
 |---------|-------------|
 | `gssh relay start` | Start relay server |
-| `gssh relay token` | Create account JWT (HMAC) |
-| `gssh relay authorize <pubkey>` | Authorize a client on relay |
-| `gssh relay revoke <id>` | Revoke client authorization |
+| `gssh relay authorize <pubkey>` | Authorize a machine on relay |
+| `gssh relay revoke <id>` | Revoke machine authorization |
 | `gssh relay machines` | List authorized machines |
+| `gssh relay trusted` | List trusted relays |
+| `gssh relay untrust <url>` | Remove relay from trusted list |
 
 ### tmux-lite Daemon
 | Command | Description |
@@ -263,10 +264,19 @@ src/
 └─────────────────┘       └─────────────────┘       └─────────────────┘
 ```
 
-### Connection Flow
+### Connection Flow (gitspace.sh Hosting)
 
-1. Machine runs `gssh serve --relay <url> --token <jwt>`
-2. Machine registers with relay (sends public keys)
+1. User logs in: `gssh auth login` (GitHub OAuth)
+2. User reserves subdomain: `gssh host reserve <name>`
+3. Machine runs `gssh serve start` (auto-starts local relay + cloudflared tunnel)
+4. Client connects via web: `https://<name>.gitspace.sh`
+5. X3DH handshake establishes session keys
+6. All terminal I/O is E2E encrypted
+
+### Connection Flow (Self-Hosted Relay)
+
+1. Machine runs `gssh serve start --relay ws://relay:4480/ws`
+2. Machine registers with relay (Ed25519 challenge-response auth)
 3. Machine creates invite: `gssh share create`
 4. Client connects with invite: `gssh connect <token>`
 5. X3DH handshake establishes session keys
@@ -280,7 +290,7 @@ src/
 | Key exchange | X25519 |
 | Symmetric encryption | AES-256-GCM |
 | Key derivation | HKDF-SHA256 |
-| JWT signing | HMAC-SHA256 |
+| Relay authentication | Ed25519 challenge-response |
 
 ## TUI/Web Shared Component Pattern
 
@@ -322,11 +332,14 @@ bun run build
 # Run TUI
 bun src/index.ts
 
-# Run relay
-RELAY_SIGNING_SECRET=secret bun src/index.ts relay start
+# Run relay (uses Ed25519 identity from keychain)
+bun src/index.ts relay start
+
+# Run serve with gitspace.sh hosting (requires auth login + host reserve)
+bun src/index.ts serve start
 
-# Run serve
-bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
+# Run serve with self-hosted relay
+bun src/index.ts serve start --relay ws://localhost:4480/ws
 ```
 
 ### Code Style
@@ -409,6 +422,7 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 | Access list | `~/gitspace/.access.json` | Authorized client public keys |
 | Machine info | `~/gitspace/.machine.json` | Machine registration |
 | Relay config | `~/gitspace/.relay.json` | Relay configuration cache |
+| Host config | `~/gitspace/host.json` | gitspace.sh subdomain config |
 | Daemon state | `~/gitspace/.serve/` | PID files, status sockets |
 | tmux-lite state | `/tmp/` | Session data (configurable via `TMUX_LITE_SESSION_DIR`) |
 
@@ -418,9 +432,8 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 |----------|-------------|---------|
 | `RELAY_PORT` | Relay server port | `4480` |
 | `RELAY_BIND` | Relay bind address | `0.0.0.0` |
-| `RELAY_SIGNING_SECRET` | Secret for HMAC JWT signing | Required |
 | `RELAY_PRIVATE_KEY` | Base64 Ed25519 private key | Uses keychain |
-| `SPACES_CURRENT_PROJECT` | Override current project | From config |
+| `RELAY_LABEL` | Label for relay identity | None |
 | `GITSPACE_API_URL` | gitspace.sh API URL | `https://api.gitspace.sh` |
 
 ### Default Values
@@ -431,9 +444,8 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 | Base branch | `main` | Global/project config |
 | Stale workspace days | `30` | Global config |
 | Relay port | `4480` | CLI/env |
-| Default relay URL | `wss://relay.gitspace.sh` | CLI |
 
 ---
 
-**Last Updated**: 2025-01
-**Runtime**: Bun / Node.js 18+
+**Last Updated**: 2026-01
+**Runtime**: Bun 1.3+

package/README.md

@@ -20,7 +20,6 @@ The following tools must be installed and available in your PATH:
 - [GitHub CLI (`gh`)](https://cli.github.com/) - for listing repositories
 - [Git](https://git-scm.com/) - for worktree management
 - [jq](https://stedolan.github.io/jq/) - for JSON processing
-- [Bun](https://bun.sh) - runtime for the CLI
 
 **GitHub Authentication**: You must authenticate the GitHub CLI before using GitSpace:
 
@@ -31,7 +30,17 @@ gh auth login
 ## Installation
 
 ```bash
-bun install -g https://github.com/inkibra/gitspace.sh
+# npm
+npm install -g gitspace
+
+# bun
+bun install -g gitspace
+
+# pnpm
+pnpm install -g gitspace
+
+# yarn
+yarn global add gitspace
 
 # Verify installation
 gssh --version

package/docs/QUICKSTART.md

@@ -8,7 +8,6 @@ Get up and running with GitSpace in 5 minutes.
 
 Install these tools first:
 
-- [Bun](https://bun.sh) - JavaScript runtime
 - [Git](https://git-scm.com/) - Version control
 - [GitHub CLI](https://cli.github.com/) - `gh auth login` before using GitSpace
 
@@ -17,7 +16,17 @@ Install these tools first:
 ## Installation
 
 ```bash
-bun install -g https://github.com/inkibra/gitspace.sh
+# npm
+npm install -g gitspace
+
+# bun
+bun install -g gitspace
+
+# pnpm
+pnpm install -g gitspace
+
+# yarn
+yarn global add gitspace
 
 # Verify
 gssh --version

package/docs/SITE_DOCS_FIGMA_MAKE.md

@@ -53,14 +53,16 @@ Prereqs (list these on docs site):
 - gh (GitHub CLI)
 - git
 - jq
-- bun
 
 Optional prereqs:
 - cloudflared (for `gssh host` commands)
 - Linear API key (for Linear integration)
 
-Install:
-- `bun install -g https://github.com/inkibra/gitspace.sh`
+Install (any package manager):
+- `npm install -g gitspace`
+- `bun install -g gitspace`
+- `pnpm install -g gitspace`
+- `yarn global add gitspace`
 - Verify: `gssh --version`
 
 ---
@@ -700,7 +702,7 @@ Feature bullets:
 Short code example:
 ```bash
 # Install
-bun install -g https://github.com/inkibra/gitspace.sh
+npm install -g gitspace
 
 # Launch the TUI
 spaces
@@ -767,7 +769,7 @@ SECTION: Quick Start
 
 ```bash
 # 1. Install
-bun install -g https://github.com/inkibra/gitspace.sh
+npm install -g gitspace
 
 # 2. Create identity
 gssh identity init
@@ -788,7 +790,7 @@ gssh serve
 
 ```bash
 # Install
-bun install -g https://github.com/inkibra/gitspace.sh
+npm install -g gitspace
 
 # Authenticate GitHub
 gh auth login
@@ -819,7 +821,7 @@ Optional:
 ### Install GitSpace
 
 ```bash
-bun install -g https://github.com/inkibra/gitspace.sh
+npm install -g gitspace
 gssh --version
 ```
 

package/landing-page/src/components/docs/DocsContent.tsx

@@ -105,8 +105,10 @@ export function DocsContent({ section }: { section: string }) {
           <h1 className="text-4xl font-bold mb-6">Quick Start</h1>
 
           <h3 className="text-xl font-semibold text-white mb-4">5-Minute Setup with gitspace.sh</h3>
-          <CodeBlock code={`# 1. Install
-bun install -g https://github.com/inkibra/gitspace.sh
+          <CodeBlock code={`# 1. Install (pick your package manager)
+npm install -g gitspace
+# or: bun install -g gitspace
+# or: pnpm install -g gitspace
 
 # 2. Create identity
 gssh identity init
@@ -124,7 +126,7 @@ gssh serve
 
           <h3 className="text-xl font-semibold text-white mb-4 mt-12">Local-Only Quick Start</h3>
           <CodeBlock code={`# Install
-bun install -g https://github.com/inkibra/gitspace.sh
+npm install -g gitspace
 
 # Authenticate GitHub
 gh auth login
@@ -146,19 +148,23 @@ gssh add my-feature # Create a workspace`} multiLine />
           <h3 className="text-xl font-semibold text-white mb-4">Prerequisites</h3>
           <p className="text-zinc-400 mb-4">Required:</p>
           <ul className="list-disc list-inside space-y-2 text-zinc-400 mb-8 ml-2">
-            <li><a href="https://bun.sh" className="text-green-400 hover:underline">Bun</a> - JavaScript runtime</li>
             <li><a href="https://git-scm.com/" className="text-green-400 hover:underline">Git</a> - Version control</li>
             <li><a href="https://cli.github.com/" className="text-green-400 hover:underline">GitHub CLI</a> - <code className="text-zinc-300">gh auth login</code> before using GitSpace</li>
             <li><a href="https://stedolan.github.io/jq/" className="text-green-400 hover:underline">jq</a> - JSON processing</li>
           </ul>
 
-          <p className="text-zinc-400 mb-4">Optional:</p>
-          <ul className="list-disc list-inside space-y-2 text-zinc-400 mb-8 ml-2">
-            <li><a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/" className="text-green-400 hover:underline">cloudflared</a> - For <code className="text-zinc-300">gssh host</code> commands</li>
-          </ul>
-
           <h3 className="text-xl font-semibold text-white mb-4">Install GitSpace</h3>
-          <CodeBlock code="bun install -g https://github.com/inkibra/gitspace.sh" />
+          <CodeBlock code={`# npm
+npm install -g gitspace
+
+# bun
+bun install -g gitspace
+
+# pnpm
+pnpm install -g gitspace
+
+# yarn
+yarn global add gitspace`} multiLine />
           <CodeBlock code="gssh --version" />
 
           <h3 className="text-xl font-semibold text-white mb-4">Authenticate GitHub CLI</h3>

package/landing-page/src/components/landing/CTA.tsx

@@ -36,7 +36,7 @@ export function CTA() {
                     <div className="space-y-2 font-mono text-sm">
                         <div className="flex">
                             <span className="text-green-500 mr-2">$</span>
-                            <span className="text-white">bun install -g https://github.com/inkibra/gitspace.sh</span>
+                            <span className="text-white">npm install -g gitspace</span>
                         </div>
                         <div className="text-zinc-500 text-xs py-1">...</div>
                         <div className="flex">

package/landing-page/src/components/landing/Features.tsx

@@ -47,7 +47,7 @@ export function Features() {
                     <TerminalWindow title="bash">
                         <div className="space-y-2 font-mono text-sm">
                             <div className="text-zinc-500"># Install</div>
-                            <div className="text-zinc-400">$ bun install -g https://github.com/inkibra/gitspace.sh</div>
+                            <div className="text-zinc-400">$ npm install -g gitspace</div>
                             <br />
                             <div className="text-zinc-500"># Launch the TUI</div>
                             <div className="text-zinc-400">$ gssh</div>
@@ -166,7 +166,7 @@ export function Features() {
                 <div>
                     <TerminalWindow title="bash">
                         <div className="space-y-2 font-mono text-sm">
-                            <div className="text-zinc-400">$ gitspace stack</div>
+                            <div className="text-zinc-400">$ gssh stack</div>
                             <div className="text-blue-400 animate-pulse">Analyzing 47 commits across 30 files...</div>
                             <br />
                             <div className="text-zinc-300">Suggested stack:</div>

package/landing-page/src/components/landing/UseCases.tsx

@@ -4,7 +4,7 @@ import { Card, CardContent } from "../../app/components/ui/card";
 export function UseCases() {
   const testimonials = [
     {
-      quote: "I run 3-4 Claude agents in parallel now. Each in its own space. I check progress from my phone while making dinner. When they're done, git stack turns the mess into reviewable PRs.",
+      quote: "I run 3-4 Claude agents in parallel now. Each in its own space. I check progress from my phone while making dinner. Context switching between tasks is instant.",
       author: "Solo founder",
       role: "Shipping 3x faster",
       stars: 5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitspace",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.0-rc.4",
   "description": "CLI for managing GitHub workspaces with git worktrees and secure remote terminal access",
   "bin": {
     "gssh": "./bin/gssh"
@@ -17,10 +17,10 @@
     "relay": "bun src/relay/index.ts"
   },
   "optionalDependencies": {
-    "@gitspace/darwin-arm64": "0.2.0-rc.2",
-    "@gitspace/darwin-x64": "0.2.0-rc.2",
-    "@gitspace/linux-x64": "0.2.0-rc.2",
-    "@gitspace/linux-arm64": "0.2.0-rc.2"
+    "@gitspace/darwin-arm64": "0.2.0-rc.4",
+    "@gitspace/darwin-x64": "0.2.0-rc.4",
+    "@gitspace/linux-x64": "0.2.0-rc.4",
+    "@gitspace/linux-arm64": "0.2.0-rc.4"
   },
   "keywords": [
     "cli",
@@ -70,5 +70,6 @@
   },
   "engines": {
     "bun": ">=1.3.5"
-  }
+  },
+  "packageManager": "pnpm@10.12.1+sha512.f0dda8580f0ee9481c5c79a1d927b9164f2c478e90992ad268bbb2465a736984391d6333d2c327913578b2804af33474ca554ba29c04a8b13060a717675ae3ac"
 }

package/src/commands/auth.ts

@@ -12,6 +12,7 @@ import { sign, serializeIdentity } from '../lib/tmux-lite/crypto/identity.js';
 import { promptPassword } from '../utils/prompts.js';
 import { logger } from '../utils/logger.js';
 import { NoIdentityError, SpacesError } from '../types/errors.js';
+import { syncHostConfig } from './host.js';
 
 // API Configuration
 const API_BASE = process.env.GITSPACE_API_URL || 'https://api.gitspace.sh';
@@ -194,6 +195,10 @@ export async function authLogin(): Promise<void> {
   logger.success('Authentication complete');
   logger.success(`Logged in as ${user.github_username}`);
   logger.success('Token saved to keychain');
+
+  // Step 6: Sync host config (fetches existing subdomains from API)
+  // Interactive mode will prompt user to select primary or reserve a subdomain
+  await syncHostConfig(true);
 }
 
 // ============================================================================

package/src/commands/host.ts

@@ -85,9 +85,11 @@ function writeHostConfig(config: HostConfig): void {
 }
 
 /**
- * Update host config after subdomain changes
+ * Sync host config from gitspace.sh API
+ * Called after login and subdomain changes to keep local config in sync
+ * @param interactive - If true, prompt user to select primary if needed
  */
-async function syncHostConfig(): Promise<void> {
+export async function syncHostConfig(interactive: boolean = false): Promise<void> {
   const token = await getSecret('GITSPACE_TOKEN');
   if (!token) return;
 
@@ -99,7 +101,40 @@ async function syncHostConfig(): Promise<void> {
 
     const subdomains: SubdomainInfo[] = await res.json();
     const activeSubdomains = subdomains.filter((s) => s.status === 'active');
-    const primary = activeSubdomains.find((s) => s.is_primary);
+
+    // No subdomains - tell user to reserve one
+    if (activeSubdomains.length === 0) {
+      if (interactive) {
+        logger.log('');
+        logger.dim('No subdomains reserved yet.');
+        logger.dim('To enable remote access, reserve a subdomain:');
+        logger.command('  gssh host reserve <name>');
+      }
+      return;
+    }
+
+    // Check for primary
+    let primary = activeSubdomains.find((s) => s.is_primary);
+
+    // If no primary set and interactive, ask user to pick one
+    if (!primary && interactive && activeSubdomains.length > 0) {
+      logger.log('');
+      logger.log('Your subdomains:');
+      activeSubdomains.forEach((s, i) => {
+        logger.log(`  ${i + 1}. ${s.subdomain}.gitspace.sh`);
+      });
+
+      if (activeSubdomains.length === 1) {
+        // Auto-set the only one as primary
+        primary = activeSubdomains[0];
+        logger.dim(`Setting ${primary.subdomain}.gitspace.sh as primary...`);
+        await hostSetPrimary(primary.subdomain);
+      } else {
+        logger.log('');
+        logger.dim('Select a primary subdomain for this machine:');
+        logger.command('  gssh host set-primary <name>');
+      }
+    }
 
     if (primary) {
       writeHostConfig({
@@ -107,6 +142,26 @@ async function syncHostConfig(): Promise<void> {
         subdomains: activeSubdomains.map((s) => s.subdomain),
         createdAt: primary.created_at,
       });
+
+      // Sync tunnel token if not present (e.g., new machine with existing account)
+      const existingToken = await getSecret(`TUNNEL_TOKEN_${primary.subdomain}`);
+      if (!existingToken) {
+        if (interactive) {
+          logger.dim(`Fetching tunnel credentials for ${primary.subdomain}.gitspace.sh...`);
+        }
+        try {
+          const tokenRes = await fetch(`${API_BASE}/subdomains/${primary.subdomain}/token`, { headers });
+          if (tokenRes.ok) {
+            const { tunnelToken } = await tokenRes.json();
+            await setSecret(`TUNNEL_TOKEN_${primary.subdomain}`, tunnelToken);
+            if (interactive) {
+              logger.success('Tunnel credentials saved');
+            }
+          }
+        } catch {
+          // Ignore token fetch errors
+        }
+      }
     }
   } catch {
     // Ignore sync errors
@@ -378,11 +433,28 @@ export async function hostStatus(): Promise<void> {
     logger.log(`Status: ${primary.status}`);
 
     // Check if tunnel token exists locally
-    const tunnelToken = await getSecret(`TUNNEL_TOKEN_${primary.subdomain}`);
+    let tunnelToken = await getSecret(`TUNNEL_TOKEN_${primary.subdomain}`);
+
+    // Auto-fetch token if missing
+    if (!tunnelToken) {
+      logger.dim('Tunnel credentials missing, fetching...');
+      try {
+        const tokenRes = await fetch(`${API_BASE}/subdomains/${primary.subdomain}/token`, { headers });
+        if (tokenRes.ok) {
+          const { tunnelToken: newToken } = await tokenRes.json();
+          await setSecret(`TUNNEL_TOKEN_${primary.subdomain}`, newToken);
+          tunnelToken = newToken;
+          logger.success('Tunnel credentials synced');
+        }
+      } catch {
+        // Ignore
+      }
+    }
+
     logger.log(`Tunnel token: ${tunnelToken ? 'configured' : 'missing'}`);
 
     if (!tunnelToken) {
-      logger.dim('Run: gssh host reserve ' + primary.subdomain + ' (to refresh token)');
+      logger.warning('Could not fetch tunnel credentials');
     }
   } catch {
     logger.log('Could not verify status (API unreachable)');

package/src/commands/serve.ts

@@ -58,6 +58,7 @@ import {
   sendShutdownCommand,
   getServeLogFile,
   setAccessCommandHandler,
+  ensureServeDaemonDir,
   type StatusResponse,
 } from '../serve/daemon.js';
 
@@ -65,7 +66,7 @@ import {
 const PACKAGE_VERSION = '1.0.0';
 
 /** Default relay URL */
-const DEFAULT_RELAY_URL = 'wss://relay.gitspace.sh';
+// No default relay - must use hosting or explicit --relay
 
 /** Local relay port for gitspace.sh hosting */
 const LOCAL_RELAY_PORT = 4480;
@@ -502,21 +503,36 @@ export async function serve(options: {
   const entries = readAccessList();
   accessList.import(entries);
 
-  // Step 3: Display info
+  // Step 3: Check for gitspace.sh hosting or explicit relay
+  const hostConfig = readHostConfig();
+  const relayUrl = options.relay; // No default - must use hosting or explicit --relay
+
+  // If no hosting config and no explicit relay, error out
+  if (!hostConfig?.subdomain && !relayUrl) {
+    throw new SpacesError(
+      'No relay configured.\n\n' +
+      'Either set up gitspace.sh hosting:\n' +
+      '  gssh auth login\n' +
+      '  gssh host reserve <subdomain>\n\n' +
+      'Or specify a relay explicitly:\n' +
+      '  gssh serve start --relay ws://localhost:4480/ws',
+      'USER_ERROR'
+    );
+  }
+
+  // Display info
   const machineIdentity = readMachineIdentity();
   const machineId = machineIdentity?.machineId ?? identity.id;
-  const relayUrl = options.relay ?? DEFAULT_RELAY_URL;
 
   logger.log('');
   logger.bold('Machine Identity:');
   logger.log(`  ID:    ${machineId}`);
-  logger.log(`  Relay: ${relayUrl}`);
+  if (relayUrl) {
+    logger.log(`  Relay: ${relayUrl}`);
+  }
   logger.log('');
   logger.dim(`Access list: ${entries.length} authorized ${entries.length === 1 ? 'client' : 'clients'}`);
   logger.log('');
-
-  // Step 3b: Check for gitspace.sh hosting
-  const hostConfig = readHostConfig();
   let localRelayServer: ReturnType<typeof createRelayServer> | null = null;
   let localRelayIdentity: ReturnType<typeof generateRelayIdentity> | null = null;
 
@@ -607,6 +623,11 @@ export async function serve(options: {
     return;
   }
 
+  // If we get here, relayUrl must be defined (checked earlier)
+  if (!relayUrl) {
+    throw new SpacesError('No relay URL configured', 'USER_ERROR');
+  }
+
   // Step 4: Create session manager
   const sessionManager = new ClientSessionManager({
     relay: relayUrl,
@@ -1207,21 +1228,28 @@ export async function serveStart(options: {
     logger.log('Starting serve daemon...');
 
     // Build args for background process
-    const args = [process.argv[1], 'serve', 'start', '--foreground'];
-    if (options.relay) args.push('--relay', options.relay);
-    if (options.relayPubkey) args.push('--relay-pubkey', options.relayPubkey);
-    args.push('--password-stdin');
+    // Detect if we're running as a compiled binary vs dev mode
+    const isCompiled = !process.execPath.endsWith('bun');
+
+    const serveArgs = ['serve', 'start', '--foreground'];
+    if (options.relay) serveArgs.push('--relay', options.relay);
+    if (options.relayPubkey) serveArgs.push('--relay-pubkey', options.relayPubkey);
+    serveArgs.push('--password-stdin');
+
+    // Build command: compiled binary runs directly, dev mode uses bun
+    const cmd = isCompiled
+      ? [process.execPath, ...serveArgs]
+      : ['bun', process.argv[1], ...serveArgs];
 
     // Write output to log file for debugging
     const logFile = getServeLogFile();
-    const { ensureServeDaemonDir } = await import('../serve/daemon.js');
     ensureServeDaemonDir();
 
     // Truncate log file at start
     await Bun.write(logFile, `[${new Date().toISOString()}] Starting serve daemon...\n`);
 
     const child = spawn({
-      cmd: ['bun', ...args],
+      cmd,
       stdin: 'pipe',
       stdout: Bun.file(logFile),
       stderr: Bun.file(logFile),
@@ -1269,20 +1297,35 @@ export async function serveStart(options: {
   // Get config
   const machineIdentity = readMachineIdentity();
   const machineId = machineIdentity?.machineId ?? identity.id;
-  const relayUrl = options.relay ?? DEFAULT_RELAY_URL;
 
   // Check for gitspace.sh hosting
   const hostConfig = readHostConfig();
+  const relayUrl = options.relay; // No default - must use hosting or explicit --relay
+
+  // If no hosting config and no explicit relay, error out
+  if (!hostConfig?.subdomain && !relayUrl) {
+    cleanupServeFiles();
+    throw new SpacesError(
+      'No relay configured.\n\n' +
+      'Either set up gitspace.sh hosting:\n' +
+      '  gssh auth login\n' +
+      '  gssh host reserve <subdomain>\n\n' +
+      'Or specify a relay explicitly:\n' +
+      '  gssh serve start --relay ws://localhost:4480/ws',
+      'USER_ERROR'
+    );
+  }
+
   let localRelayServer: ReturnType<typeof createRelayServer> | null = null;
   let localRelayIdentity: ReturnType<typeof generateRelayIdentity> | null = null;
-  let effectiveRelayUrl = relayUrl;
+  let effectiveRelayUrl = relayUrl || '';
 
   // Initialize daemon state
   setDaemonState({
     version: PACKAGE_VERSION,
     startTime: Date.now(),
     relay: {
-      url: relayUrl,
+      url: effectiveRelayUrl,
       status: 'connecting',
     },
     clients: 0,
@@ -1373,7 +1416,7 @@ export async function serveStart(options: {
 
   // Save relay config for share/access commands
   writeRelayConfig({
-    relayUrl,
+    relayUrl: effectiveRelayUrl,
     machineId,
     savedAt: Date.now(),
   });

package/src/commands/share.ts

@@ -27,11 +27,6 @@ import { SpacesError, NoIdentityError, InvalidPasswordError } from '../types/err
 import chalk from 'chalk';
 import { createHash } from 'crypto';
 
-/**
- * Default relay URL
- */
-const DEFAULT_RELAY_URL = 'wss://relay.gitspace.sh';
-
 /**
  * Duration string formats supported:
  * - "1h" -> 1 hour

package/src/core/bundle.ts

@@ -15,6 +15,8 @@ import {
 } from 'fs';
 import { join, basename, resolve, sep } from 'path';
 import { tmpdir } from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
 import { SpacesError } from '../types/errors.js';
 import { logger } from '../utils/logger.js';
 import type { SpacesBundle, LoadedBundle } from '../types/bundle.js';
@@ -140,8 +142,6 @@ export async function loadBundleFromUrl(url: string): Promise<LoadedBundle> {
     writeFileSync(zipPath, Buffer.from(arrayBuffer));
 
     // Extract using unzip command
-    const { exec } = await import('child_process');
-    const { promisify } = await import('util');
     const execAsync = promisify(exec);
 
     await execAsync(`unzip -q "${zipPath}" -d "${tempDir}"`);

package/src/index.ts

@@ -5,9 +5,37 @@
  * Manages GitHub workspaces with git worktrees and secure remote terminal access
  */
 
+// Internal command: run tmux-lite server directly (for compiled binary)
+// This must be checked before any other imports to avoid loading unnecessary modules
+if (process.argv.includes('--internal-tmux-server')) {
+	// Pass through --test flag if present
+	if (process.argv.includes('--test')) {
+		process.env.TMUX_LITE_SOCKET = '/tmp/tmux-lite-test.sock';
+		process.env.TMUX_LITE_SESSION_DIR = '/tmp/tmux-lite-test';
+		process.env.TMUX_LITE_PID_FILE = '/tmp/tmux-lite-test.pid';
+	}
+	// Import and run server (module auto-starts on import)
+	await import('./lib/tmux-lite/server.js');
+	// Keep process alive - server runs via Bun.listen() which is async
+	// We need to prevent the rest of this file from executing
+	await new Promise(() => {}); // Block forever
+}
+
 import { Command } from 'commander'
+import { readFileSync } from 'fs'
+import { join } from 'path'
 import { isFirstTimeSetup, initializeSpaces } from './core/config.js'
-import { VERSION } from './version.generated.js'
+import { VERSION as GENERATED_VERSION } from './version.generated.js'
+
+// Read version from package.json in dev, fall back to generated for compiled binary
+let VERSION = GENERATED_VERSION
+try {
+	const pkgPath = join(import.meta.dir, '../package.json')
+	const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+	VERSION = pkg.version
+} catch {
+	// Compiled binary - use generated version
+}
 import { logger } from './utils/logger.js'
 import { SpacesError } from './types/errors.js'
 import { addProject, addWorkspace } from './commands/add.js'

package/src/lib/tmux-lite/cli.ts

@@ -67,9 +67,22 @@ if (isTestMode) {
   process.env.TMUX_LITE_SESSION_DIR = "/tmp/tmux-lite-test";
 }
 
-const getServerCommand = (): string[] => (
-  isTestMode ? ["bun", "run", SERVER_SCRIPT, "--test"] : ["bun", "run", SERVER_SCRIPT]
-);
+const getServerCommand = (): string[] => {
+  // Detect if we're running as a compiled binary (not bun)
+  const isCompiled = !process.execPath.endsWith('bun');
+
+  if (isCompiled) {
+    // Use the binary with internal flag
+    return isTestMode
+      ? [process.execPath, '--internal-tmux-server', '--test']
+      : [process.execPath, '--internal-tmux-server'];
+  }
+
+  // Dev mode: use bun run
+  return isTestMode
+    ? ['bun', 'run', SERVER_SCRIPT, '--test']
+    : ['bun', 'run', SERVER_SCRIPT];
+};
 
 // Check if we're already inside a tmux-lite session
 export function isNested(): boolean {
@@ -605,8 +618,10 @@ async function main() {
     console.log("Starting server...");
     spawn({
       cmd: getServerCommand(),
-      stdout: "inherit",
-      stderr: "inherit",
+      // Use "ignore" so server doesn't inherit CLI's stdout/stderr
+      // This allows CLI to exit cleanly when piped
+      stdout: "ignore",
+      stderr: "ignore",
     });
     await Bun.sleep(300);
     if (!(await isServerRunning())) {
@@ -787,10 +802,23 @@ In session:
   }
 }
 
+// Commands that are non-interactive and should exit immediately after completion
+const NON_INTERACTIVE_COMMANDS = new Set([
+  "list", "ls", "kill", "kill-server", "inbox", "inbox-clear", "status", "version"
+]);
+
 // Only run CLI when executed directly, not when imported as a module
 if (import.meta.main) {
-  main().catch(e => {
-    console.error(e.message);
-    process.exit(1);
-  });
+  main()
+    .then(() => {
+      // Force exit after non-interactive commands complete
+      // Some socket references may keep the event loop alive otherwise
+      if (NON_INTERACTIVE_COMMANDS.has(cmd)) {
+        process.exit(0);
+      }
+    })
+    .catch(e => {
+      console.error(e.message);
+      process.exit(1);
+    });
 }

package/src/lib/tmux-lite/server-lifecycle.test.ts

@@ -0,0 +1,208 @@
+/**
+ * E2E tests for tmux-lite server lifecycle
+ *
+ * Tests server start, stop, and restart scenarios including
+ * proper cleanup of socket files.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { spawn } from "bun";
+import { existsSync, unlinkSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+
+// Use the same paths as --test mode in cli.ts and server.ts
+const TEST_SOCKET = "/tmp/tmux-lite-test.sock";
+const TEST_SESSION_DIR = "/tmp/tmux-lite-test";
+const CLI_SCRIPT = join(import.meta.dir, "cli.ts");
+
+/**
+ * Helper to run CLI commands in test mode
+ */
+async function runCli(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = spawn({
+    cmd: ["bun", "run", CLI_SCRIPT, command, "--test"],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  // Give server time to initialize after CLI returns
+  await Bun.sleep(500);
+
+  return { stdout, stderr, exitCode };
+}
+
+/**
+ * Helper to check if server is running by checking socket exists and responds
+ */
+async function isServerRunning(): Promise<boolean> {
+  if (!existsSync(TEST_SOCKET)) return false;
+
+  try {
+    const result = await runCli("list");
+    // If we can list sessions, server is running
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Helper to wait for a condition with timeout
+ */
+async function waitFor(
+  condition: () => Promise<boolean>,
+  timeoutMs: number = 5000,
+  intervalMs: number = 100
+): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await condition()) return true;
+    await Bun.sleep(intervalMs);
+  }
+  return false;
+}
+
+/**
+ * Force cleanup any leftover test artifacts
+ */
+function forceCleanup(): void {
+  try { unlinkSync(TEST_SOCKET); } catch {}
+  try { rmSync(TEST_SESSION_DIR, { recursive: true, force: true }); } catch {}
+}
+
+describe("tmux-lite server lifecycle", () => {
+  beforeEach(() => {
+    // Ensure clean state before each test
+    forceCleanup();
+    mkdirSync(TEST_SESSION_DIR, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Kill server if still running and cleanup
+    try {
+      await runCli("kill-server");
+      await Bun.sleep(200); // Wait for cleanup
+    } catch {}
+    forceCleanup();
+  });
+
+  describe("server start", () => {
+    it("should start server and create socket file", async () => {
+      // Socket should not exist initially
+      expect(existsSync(TEST_SOCKET)).toBe(false);
+
+      // Start server by running any command (list auto-starts)
+      const result = await runCli("list");
+
+      // Wait for server to be ready
+      const started = await waitFor(async () => existsSync(TEST_SOCKET));
+      expect(started).toBe(true);
+
+      // Server should be running
+      const running = await isServerRunning();
+      expect(running).toBe(true);
+    });
+
+    it("should not fail if server is already running", async () => {
+      // Start server first time
+      await runCli("list");
+      await waitFor(async () => existsSync(TEST_SOCKET));
+
+      // Run another command - should not fail
+      const result = await runCli("list");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("server stop", () => {
+    it("should stop server and remove socket file", async () => {
+      // Start server
+      await runCli("list");
+      await waitFor(async () => existsSync(TEST_SOCKET));
+      expect(existsSync(TEST_SOCKET)).toBe(true);
+
+      // Stop server
+      await runCli("kill-server");
+
+      // Wait for socket to be cleaned up
+      const cleaned = await waitFor(async () => !existsSync(TEST_SOCKET), 2000);
+      expect(cleaned).toBe(true);
+
+      // Socket file should be removed
+      expect(existsSync(TEST_SOCKET)).toBe(false);
+    });
+
+    it("should not fail if server is not running", async () => {
+      // Ensure server is not running
+      expect(existsSync(TEST_SOCKET)).toBe(false);
+
+      // Stop should handle gracefully
+      const result = await runCli("kill-server");
+      // CLI shows "Server not running" but exits cleanly
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("server restart cycle", () => {
+    it("should successfully restart after stop (socket cleanup regression test)", async () => {
+      // This is the main regression test for the socket cleanup fix
+
+      // Start server
+      await runCli("list");
+      const started1 = await waitFor(async () => existsSync(TEST_SOCKET));
+      expect(started1).toBe(true);
+
+      // Stop server
+      await runCli("kill-server");
+      const stopped = await waitFor(async () => !existsSync(TEST_SOCKET), 2000);
+      expect(stopped).toBe(true);
+
+      // Start server again - THIS WAS FAILING before the fix
+      // because the socket file wasn't being cleaned up
+      await runCli("list");
+      const started2 = await waitFor(async () => existsSync(TEST_SOCKET));
+      expect(started2).toBe(true);
+
+      // Verify server is actually running
+      const running = await isServerRunning();
+      expect(running).toBe(true);
+    });
+
+    it("should handle multiple restart cycles", async () => {
+      for (let i = 0; i < 3; i++) {
+        // Start
+        await runCli("list");
+        const started = await waitFor(async () => existsSync(TEST_SOCKET));
+        expect(started).toBe(true);
+
+        // Verify running
+        const running = await isServerRunning();
+        expect(running).toBe(true);
+
+        // Stop
+        await runCli("kill-server");
+        const stopped = await waitFor(async () => !existsSync(TEST_SOCKET), 2000);
+        expect(stopped).toBe(true);
+      }
+    }, 15000); // Increase timeout for 3 cycles
+  });
+
+  describe("stale socket handling", () => {
+    it("should clean up stale socket on server start", async () => {
+      // Create a stale socket file (simulating crashed server)
+      Bun.write(TEST_SOCKET, "stale");
+      expect(existsSync(TEST_SOCKET)).toBe(true);
+
+      // Start server - should clean up stale socket and start fresh
+      await runCli("list");
+      const started = await waitFor(async () => {
+        // Socket exists AND server responds
+        return await isServerRunning();
+      });
+      expect(started).toBe(true);
+    });
+  });
+});

package/src/lib/tmux-lite/server.ts

@@ -1161,7 +1161,11 @@ Bun.listen({
             res = { type: "ok" };
             if (socketState.writer) socketState.writer.write(encodeRouterMessage(res));
             else socket.write(encodeRouterMessage(res));
-            setTimeout(() => process.exit(0), 100);
+            // Clean up socket file after sending response, before exit
+            setTimeout(() => {
+              try { unlinkSync(ROUTER_SOCKET); } catch {}
+              process.exit(0);
+            }, 100);
             return;
 
           case "inbox":

package/src/relay/server.ts

@@ -68,25 +68,27 @@ function getContentType(pathname: string): string {
  * Serve a static file - tries embedded assets first, falls back to filesystem
  */
 async function serveStaticFile(pathname: string): Promise<Response | null> {
+  // Normalize path for content type (/ -> /index.html)
+  const normalizedPath = pathname === "/" ? "/index.html" : pathname;
+
   // Try embedded assets first (compiled binary)
   if (hasEmbeddedAssets() && embeddedAssets) {
     const blob = embeddedAssets.getEmbeddedFile(pathname);
     if (blob) {
       return new Response(blob, {
-        headers: { "Content-Type": getContentType(pathname) },
+        headers: { "Content-Type": getContentType(normalizedPath) },
       });
     }
   }
 
   // Fall back to filesystem (development mode)
-  const filePath = pathname === "/" ? "/index.html" : pathname;
-  const resolvedPath = resolveAssetPath(filePath);
+  const resolvedPath = resolveAssetPath(normalizedPath);
   if (!resolvedPath) return null;
 
   const file = Bun.file(resolvedPath);
   if (await file.exists()) {
     return new Response(file, {
-      headers: { "Content-Type": getContentType(pathname) },
+      headers: { "Content-Type": getContentType(normalizedPath) },
     });
   }
 

package/src/shared/providers/RemoteMachineProvider.ts

@@ -5,6 +5,7 @@
  * through the relay server with encrypted communication.
  */
 
+import WebSocket from 'ws';
 import type {
   MachineProvider,
   CreateSessionOptions,
@@ -18,9 +19,6 @@ import type {
   SessionStream,
 } from '../types.js';
 
-// Use dynamic import for WebSocket to support both Node and browser
-// In Node, we use the 'ws' package; in browser, we use native WebSocket
-
 /**
  * Common WebSocket interface for both Node.js (ws package) and browser environments
  */
@@ -86,9 +84,6 @@ export class RemoteMachineProvider implements MachineProvider {
    * Connect to relay server
    */
   async connect(): Promise<void> {
-    // Dynamic import for ws module (Node.js)
-    const { default: WebSocket } = await import('ws');
-
     return new Promise((resolve, reject) => {
       const url = new URL(this.config.relayUrl);
       url.searchParams.set('role', 'client');

package/src/tui/hooks/useInboxTUI.ts

@@ -7,7 +7,12 @@
 import { useCallback } from 'react';
 import { spawn } from 'child_process';
 import { useInbox, type UseInboxProps, type UseInboxReturn } from '../../shared/components/Inbox.js';
-import type { InboxItem } from '../../lib/tmux-lite/cli.js';
+import {
+  clearInbox,
+  markInboxRead,
+  listSessions,
+  type InboxItem,
+} from '../../lib/tmux-lite/cli.js';
 
 interface UseTUIInboxOptions {
   items: InboxItem[];
@@ -38,25 +43,21 @@ export function useTUIInbox(options: UseTUIInboxOptions): UseTUIInboxReturn {
 
   // Clear a single inbox item
   const onClearItem = useCallback(async (itemId: string) => {
-    const { clearInbox } = await import('../../lib/tmux-lite/cli.js');
     await clearInbox(itemId);
   }, []);
 
   // Clear all inbox items
   const onClearAll = useCallback(async () => {
-    const { clearInbox } = await import('../../lib/tmux-lite/cli.js');
     await clearInbox();
   }, []);
 
   // Mark an item as read
   const onMarkRead = useCallback(async (itemId: string) => {
-    const { markInboxRead } = await import('../../lib/tmux-lite/cli.js');
     await markInboxRead(itemId);
   }, []);
 
   // Attach to a session
   const onAttachSession = useCallback(async (sessionId: string) => {
-    const { listSessions } = await import('../../lib/tmux-lite/cli.js');
     const sessions = await listSessions();
     const session = sessions.find(s => s.id === sessionId);
 

package/src/tui/hooks/useRemoteMachines.ts

@@ -6,8 +6,10 @@
  */
 
 import { useState, useCallback, useEffect, useRef } from 'react';
+import WebSocket from 'ws';
 import type { MachineInfo } from '../../shared/components/index.js';
 import type { MachineProvider } from '../../shared/providers/index.js';
+import { getLocalMachineProvider, createRemoteMachineProvider } from '../../shared/providers/index.js';
 import type WS from 'ws';
 
 export interface RelayConfig {
@@ -78,7 +80,6 @@ export function useRemoteMachines(options: UseRemoteMachinesOptions = {}): UseRe
     setError(null);
 
     try {
-      const { default: WebSocket } = await import('ws');
       const socket = new WebSocket(relayConfig.url);
 
       socket.on('open', () => {
@@ -147,7 +148,6 @@ export function useRemoteMachines(options: UseRemoteMachinesOptions = {}): UseRe
 
     if (isLocal(machine)) {
       // Return local provider
-      const { getLocalMachineProvider } = await import('../../shared/providers/index.js');
       return getLocalMachineProvider();
     }
 
@@ -157,7 +157,6 @@ export function useRemoteMachines(options: UseRemoteMachinesOptions = {}): UseRe
       return null;
     }
 
-    const { createRemoteMachineProvider } = await import('../../shared/providers/index.js');
     return createRemoteMachineProvider({
       relayUrl: relayConfig.url,
       machineId: machine.machineId,

package/npm/darwin-arm64/package.json

@@ -1,20 +0,0 @@
-{
-  "name": "@gitspace/darwin-arm64",
-  "version": "0.2.0-rc.2",
-  "description": "GitSpace CLI binary for darwin-arm64",
-  "os": [
-    "darwin"
-  ],
-  "cpu": [
-    "arm64"
-  ],
-  "bin": {
-    "gssh-darwin-arm64": "bin/gssh"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/inkibra/gitspace.sh.git"
-  },
-  "homepage": "https://gitspace.sh",
-  "license": "SEE LICENSE IN LICENSE"
-}