Code formatting and documentation updates

- Apply oxfmt formatting to ws-shell.ts
- Documentation updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: gricha

README.md

@@ -1,161 +1,159 @@
-# Workspace CLI
+# Workspace
 
 [![Tests](https://github.com/subroutinecom/workspace/actions/workflows/test.yml/badge.svg)](https://github.com/subroutinecom/workspace/actions/workflows/test.yml)
 [![npm version](https://badge.fury.io/js/@subroutinecom%2Fworkspace.svg)](https://www.npmjs.com/package/@subroutinecom/workspace)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Containerized development environments with Docker-in-Docker, SSH access, and persistent storage.
+Isolated, self-hosted workspaces accessible over Tailscale. AI coding agents, web UI, and remote terminal access.
 
-## Install
+## Features
+
+- **AI Coding Agents** - Claude Code, OpenCode, GitHub Copilot pre-installed
+- **Self-Hosted** - Run on your own hardware, full control
+- **Remote Access** - Use from anywhere via Tailscale, CLI, web, or SSH
+- **Web UI** - Manage workspaces from your browser
+- **Isolated Environments** - Each workspace runs in its own container
+
+## Setup
+
+### Install
 
 ```bash
 npm install -g @subroutinecom/workspace
 ```
 
-## Quick Start
+Or with curl:
 
 ```bash
-# Initialize in your project
-cd myproject
-workspace init
-
-# Edit .workspace.yml, then start
-workspace start
-workspace shell        # SSH into container
-workspace proxy        # Port forwarding (separate terminal)
+curl -fsSL https://workspace.subroutine.com/install.sh | sh
 ```
 
-## Configuration
+### Build Base Image
 
-### Project Configuration
+```bash
+ws build
+```
 
-`.workspace.yml` in your project:
+### Start Agent
 
-```yaml
-repo:
-  remote: git@github.com:user/repo.git
-  branch: main
-
-bootstrap:
-  scripts:
-    - scripts/install-deps.sh
-
-forwards:
-  - 3000
-  - 5173
-  - "8000-8010"
-
-mounts:
-  - ./local:/home/workspace/otherLocalData
-  - ~/data:/data:ro
+```bash
+ws agent start
 ```
 
-### User Configuration
+Web UI: **http://localhost:7391**
 
-`~/.workspaces/config.yml` for user-specific settings across all workspaces:
+The agent runs on port 7391 by default. For remote access:
 
-```yaml
-ssh:
-  # Default SSH key (optional - uses heuristic if not specified)
-  defaultKey: ~/.ssh/id_ed25519
-
-  # Per-repository key overrides (supports wildcards)
-  repos:
-    "git@github.com:user/private-repo.git": ~/.ssh/id_github_personal
-    "git@github.com:company/*": ~/.ssh/id_github_work
-
-bootstrap:
-  scripts:
-    - userscripts # Directory: runs all executable files alphabetically
+```bash
+ws agent start --host 0.0.0.0
 ```
 
-User config is automatically created on first run with `userscripts` directory reference. Paths are relative to `~/.workspaces/`. Directories auto-expand to run all executable files. Configuration is merged with project config - user bootstrap scripts run **after** project scripts.
+### Create & Use Workspaces
 
-**SSH Configuration:**
+**Via CLI:**
 
-- All SSH keys from `~/.ssh/` are copied to containers
-- Specify `defaultKey` to set which key is used by default for git operations
-- Per-repository overrides support exact matches and wildcard patterns
-- If no `defaultKey` is specified, the CLI uses SSH agent keys or falls back to `id_ed25519`, `id_ecdsa`, or `id_rsa`
-- The selected key is automatically configured in git and SSH config inside containers
+```bash
+# Create workspace
+ws create myproject
 
-**Bootstrap scripts** run as `workspace` user with passwordless sudo.
+# Or clone a repo
+ws create myproject --clone git@github.com:user/repo.git
 
-**Mounts** format: `source:target[:mode]`. Relative paths resolve from config directory. Tilde expands to home. By default workspace mounts your host $HOME at `/host/home` (read-only).
+# SSH into workspace
+ws list  # Find SSH port
+ssh -p 2201 workspace@localhost
 
-**Forwards** creates SSH tunnels when running `workspace proxy <name>`.
+# Manage workspaces
+ws start myproject
+ws stop myproject
+ws delete myproject
+```
 
-## Commands
+**Via Web UI:**
 
-```bash
-# Lifecycle
-workspace start [name]             # Start workspace (auto-builds image)
-workspace stop [name]              # Stop workspace
-workspace destroy [name...] [-f]   # Remove container + volumes
-workspace status [name]            # Show state (CPU, memory, ports)
-
-# Development
-workspace shell [name] [-c "cmd"]  # SSH into container
-workspace proxy [name]             # Port forwarding tunnel
-workspace logs [name] [-f]         # Container logs
-
-# Discovery
-workspace list                     # Find all .workspace.yml files
-workspace config [name]            # Show resolved configuration
-workspace doctor                   # Check prerequisites
-
-# Image/BuildKit
-workspace build [--no-cache]       # Build base image
-workspace buildkit [--status]      # Manage shared BuildKit
-```
+Open http://localhost:7391 and click "+" to create a workspace.
 
-Commands run from project directory use that workspace. Or specify name from anywhere.
+## Security
 
-## What's Inside
+Workspace is designed for use within **secure networks** like [Tailscale](https://tailscale.com). The web UI and API have no authentication, making them ideal for private networks where you can safely access workspaces remotely without additional security concerns.
 
-- **OS**: Ubuntu 24.04 LTS
-- **Docker**: CE + Compose + BuildKit
-- **Languages**: Node.js 22, Python 3
-- **Editor**: Neovim v0.11.4 + LazyVim
-- **Tools**: Git, GitHub CLI, ripgrep, fd-find, jq, curl, wget, rsync
-- **User**: `workspace` with passwordless sudo
+For public internet exposure, place behind a reverse proxy with authentication.
 
-## User Scripts
+## Configuration
 
-Add executable scripts to `~/.workspaces/userscripts/` - they run automatically in all workspaces:
+Configure credentials and environment variables via Web UI → Settings or edit `~/.workspace-agent/config.yaml`:
 
 ```yaml
-# ~/.workspaces/config.yml (auto-created on first run)
-bootstrap:
-  scripts:
-    - userscripts # Runs all executable files in directory
+credentials:
+  env:
+    ANTHROPIC_API_KEY: "sk-ant-..."
+    OPENAI_API_KEY: "sk-..."
+    GITHUB_TOKEN: "ghp_..."
+  files:
+    ~/.ssh/id_ed25519: ~/.ssh/id_ed25519
+    ~/.gitconfig: ~/.gitconfig
 ```
 
-Example script:
+Restart workspaces to apply changes.
+
+## What's Inside Each Workspace
+
+- Ubuntu 24.04 LTS
+- Node.js 22, Python 3, Go
+- Docker (for containerized development)
+- Neovim + LazyVim
+- Git, GitHub CLI, ripgrep, fd-find, jq
+- Claude Code, OpenCode, Codex CLI
+
+## Commands
 
 ```bash
-# ~/.workspaces/userscripts/setup-shell.sh
-#!/bin/bash
-echo "Setting up shell configuration..."
-cp /host/home/.zshrc ~/.zshrc
+# Agent
+ws agent start [--port PORT] [--host HOST]
+ws agent stop
+ws agent status
+
+# Workspaces
+ws create <name> [--clone URL]
+ws start <name>
+ws stop <name>
+ws delete <name>
+ws list
+ws logs <name> [-f]
+
+# Build
+ws build [--no-cache]
+ws doctor
 ```
 
-Make scripts executable: `chmod +x ~/.workspaces/userscripts/setup-shell.sh`
+## Documentation
 
-**Directory expansion**: Point at a directory to run all executable files alphabetically. Or specify individual scripts for precise control.
+Full docs at https://workspace.subroutine.com/docs
 
-User scripts execute after project bootstrap scripts in the order listed.
+Or run locally:
 
-## Testing
+```bash
+cd docs
+npm install
+npm start
+```
+
+## Development
 
 ```bash
-npm test
+git clone https://github.com/subroutinecom/workspace.git
+cd workspace
+bun install
+bun run build
 ```
 
-## Prerequisites
+Run tests:
+
+```bash
+bun run validate  # Lint, typecheck, build, test
+bun run test      # Tests only
+```
 
-- Docker Desktop or Engine
-- SSH client + ssh-keygen
-- Node.js 18+
+## License
 
-Run `workspace doctor` to verify.
+MIT

docs/docs/getting-started.md

@@ -10,7 +10,7 @@ sidebar_position: 3
 ws agent start
 ```
 
-Web UI: `http://localhost:8420`
+Web UI: `http://localhost:7391`
 
 Options:
 ```bash
@@ -27,7 +27,7 @@ ws create myproject --clone git@github.com:user/repo.git
 ```
 
 Web UI:
-1. Open `http://localhost:8420`
+1. Open `http://localhost:7391`
 2. Click "+"
 3. Enter name
 4. Create

docs/docs/installation.md

@@ -31,7 +31,7 @@ bun link
 ws build
 ```
 
-Takes 5-10 minutes. Only needed once.
+Builds the Ubuntu 24.04 base image with dev tools. Takes 5-10 minutes, only needed once.
 
 ## Verify
 

docs/docs/introduction.md

@@ -4,27 +4,27 @@ sidebar_position: 1
 
 # Introduction
 
-Workspace creates isolated Docker-in-Docker development environments.
+Workspace creates isolated, containerized development environments accessible from anywhere.
 
 ## Features
 
-- **Isolated** - Each project in its own container
-- **Reproducible** - Same environment everywhere
+- **Isolated** - Each workspace runs in its own container
+- **Self-Hosted** - Run on your hardware, full control
 - **AI-Ready** - Claude Code, OpenCode, GitHub Copilot pre-installed
-- **Remote** - Access via Web UI, CLI, or SSH
+- **Remote Access** - Use over Tailscale, web UI, CLI, or SSH
 
 ## What's Inside
 
 - Ubuntu 24.04 LTS
-- Docker CE + Compose + BuildKit
 - Node.js 22, Python 3, Go
+- Docker (for containerized workflows)
 - Neovim + LazyVim
 - Git, GitHub CLI, common tools
 - Claude Code, OpenCode, Codex CLI
 
 ## Access
 
-- **Web UI** - Browser interface (port 8420)
+- **Web UI** - Browser interface (port 7391)
 - **CLI** - `ws` command
 - **SSH** - Direct terminal access
 

docs/docs/troubleshooting.md

@@ -200,9 +200,9 @@ docker volume rm workspace-<name>
 
 1. **Check if port is in use:**
    ```bash
-   lsof -i :8420
+   lsof -i :7391
    # or
-   netstat -tuln | grep 8420
+   netstat -tuln | grep 7391
    ```
 
 2. **Use a different port:**
@@ -239,19 +239,19 @@ docker volume rm workspace-<name>
 1. **Verify agent is running:**
    ```bash
    ws agent status
-   # Should show "Agent is running on port 8420"
+   # Should show "Agent is running on port 7391"
    ```
 
 2. **Test API directly:**
    ```bash
-   curl http://localhost:8420/rpc
+   curl http://localhost:7391/rpc
    # Should return JSON response
    ```
 
 3. **Check firewall (Linux):**
    ```bash
    sudo ufw status
-   sudo ufw allow 8420
+   sudo ufw allow 7391
    ```
 
 4. **Try different browser:**

docs/docs/web-ui.md

@@ -4,7 +4,7 @@ sidebar_position: 6
 
 # Web UI
 
-Access: `http://localhost:8420`
+Access: `http://localhost:7391`
 
 ## Features
 

docs/docusaurus.config.ts

@@ -6,7 +6,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 const config: Config = {
   title: 'Workspace',
-  tagline: 'Containerized development environments with Docker-in-Docker',
+  tagline: 'Isolated, self-hosted workspaces accessible over Tailscale',
   favicon: 'img/favicon.ico',
 
   // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future