StacyOS · arpan-mondal · May 11, 2026 · May 11, 2026
diff --git a/docs.json b/docs.json
@@ -48,6 +48,7 @@
         "pages": [
           "index",
           "docs/getting-started/what-is-stacyvm",
+          "docs/getting-started/developer-onboarding",
           "docs/getting-started/prerequisites",
           "docs/getting-started/quickstart",
           "docs/getting-started/installation",

diff --git a/docs/getting-started/developer-onboarding.mdx b/docs/getting-started/developer-onboarding.mdx
@@ -0,0 +1,179 @@
+---
+title: "Developer Onboarding"
+description: "Start StacyVM with one command, verify the server, run code in a sandbox, and troubleshoot common setup issues."
+---
+
+This is the fastest path for a developer who wants StacyVM running locally.
+
+## Start StacyVM
+
+Run this in a fresh terminal:
+
+```bash
+npx stacyvm-setup@latest
+```
+
+The setup command clones StacyVM if needed, installs package dependencies, downloads Go modules, builds the binary, and starts the server at `http://localhost:7423`.
+
+<Note>
+  You still need Docker Desktop or Docker Engine running locally. If Docker is not reachable, setup stops and prints the fix for your operating system.
+</Note>
+
+## Clean Verification Flow
+
+Use this flow when you want to verify each step before starting the server.
+
+### 1. Verify The Npm Package
+
+```bash
+npm view stacyvm-setup name version bin --json
+npx stacyvm-setup@latest --help
+```
+
+### 2. Run Setup Without Starting The Server
+
+This checks clone, dependency installation, Go module download, and build behavior safely.
+
+```bash
+mkdir -p /tmp/stacyvm-npx-test
+cd /tmp/stacyvm-npx-test
+
+npx stacyvm-setup@latest \
+  --dir ./stacyvm \
+  --no-start
+```
+
+Expected result:
+
+```bash
+./stacyvm/stacyvm
+```
+
+### 3. Start StacyVM
+
+```bash
+cd /tmp/stacyvm-npx-test/stacyvm
+./stacyvm serve
+```
+
+Leave this terminal running.
+
+### 4. Check Health
+
+In a second terminal:
+
+```bash
+curl http://localhost:7423/api/v1/live
+curl http://localhost:7423/api/v1/ready
+```
+
+### 5. Create A Sandbox
+
+```bash
+curl -sS -X POST http://localhost:7423/api/v1/sandboxes \
+  -H "Content-Type: application/json" \
+  -d '{"image":"python:3.12","ttl":"10m"}'
+```
+
+Copy the returned sandbox ID.
+
+### 6. Run Code
+
+```bash
+export SANDBOX_ID="PASTE_ID_HERE"
+
+curl -sS -X POST "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}/exec" \
+  -H "Content-Type: application/json" \
+  -d '{"command":"python3 -c \"print(40 + 2)\"","timeout":"10s"}'
+```
+
+Expected output includes:
+
+```json
+"stdout": "42\n"
+```
+
+### 7. Destroy The Sandbox
+
+```bash
+curl -sS -X DELETE "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}"
+```
+
+### 8. Optional Full One-Command Run
+
+After the verification flow passes:
+
+```bash
+cd /tmp
+npx stacyvm-setup@latest --dir ./stacyvm-full-test
+```
+
+This sets up StacyVM and starts the server directly.
+
+## Common Fixes
+
+<AccordionGroup>
+  <Accordion title="Docker CLI is installed, but the daemon is not reachable">
+    Start Docker, then verify it:
+
+    ```bash
+    docker info
+    docker run --rm hello-world
+    ```
+
+    On macOS, start Docker Desktop:
+
+    ```bash
+    open -a Docker
+    ```
+
+    On Windows, run setup inside WSL 2 Ubuntu and enable Docker Desktop WSL integration for that distro.
+  </Accordion>
+
+  <Accordion title="Go is missing">
+    Install Go, then rerun setup.
+
+    macOS:
+
+    ```bash
+    brew install go
+    ```
+
+    Ubuntu or Debian:
+
+    ```bash
+    sudo apt update
+    sudo apt install -y golang-go
+    ```
+  </Accordion>
+
+  <Accordion title="Port 7423 is already in use">
+    Check what is listening:
+
+    ```bash
+    lsof -iTCP:7423 -sTCP:LISTEN
+    ```
+
+    Stop that process, or use the StacyVM server that is already running.
+  </Accordion>
+
+  <Accordion title="You only want to test clone and build">
+    Skip server startup:
+
+    ```bash
+    npx stacyvm-setup@latest --dir ./stacyvm --no-start
+    ```
+
+    If Docker is not running yet, you can also skip Docker validation:
+
+    ```bash
+    npx stacyvm-setup@latest --dir ./stacyvm --no-start --skip-docker-check
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+- Use the [Quickstart](/docs/getting-started/quickstart) for SDK and REST examples.
+- Review [Core Concepts](/docs/getting-started/core-concepts) when you want the mental model.
+- Use [Production Deployment](/docs/deployment) before exposing StacyVM to other users.
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
@@ -33,19 +33,11 @@ This checks the host, builds StacyVM, and starts the API server.
 You can also use the npm/npx bootstrapper:
 
 ```bash
-npx stacyvm-setup@latest \
-  --branch phase-14-worker-identity-hardening
+npx stacyvm-setup@latest
 ```
 
 That command can clone the repo, install Node package dependencies, download Go modules, build StacyVM, and start the server. It does not install Docker Desktop or Go for you.
 
-To test the branch directly from GitHub instead of npm, use:
-
-```bash
-npx github:StacyOS/stacyvm#phase-14-worker-identity-hardening stacyvm-setup \
-  --branch phase-14-worker-identity-hardening
-```
-
 ## Option 1: Release Binary
 
 Use a signed GitHub release for production-like installs.

diff --git a/docs/getting-started/prerequisites.mdx b/docs/getting-started/prerequisites.mdx
@@ -42,13 +42,12 @@ make dev
 If you prefer an npm/npx-driven setup, use:
 
 ```bash
-npx stacyvm-setup@latest \
-  --branch phase-14-worker-identity-hardening
+npx stacyvm-setup@latest
 ```
 
 The npm setup command can clone StacyVM, run `npm install` for the web, SDK, and TypeScript example packages, download Go modules, build the StacyVM binary, and start the server. It still expects Docker and Go to be installed on the host.
 
-To test the branch directly from GitHub instead of npm, use:
+To test a non-main branch directly from GitHub, use:
 
 ```bash
 npx github:StacyOS/stacyvm#phase-14-worker-identity-hardening stacyvm-setup \
@@ -247,7 +246,6 @@ mkdir -p /tmp/stacyvm-npx-test
 cd /tmp/stacyvm-npx-test
 
 npx stacyvm-setup@latest \
-  --branch phase-14-worker-identity-hardening \
   --dir ./stacyvm \
   --no-start
 ```
@@ -309,7 +307,6 @@ After that passes, you can test the full one-command path:
 ```bash
 cd /tmp
 npx stacyvm-setup@latest \
-  --branch phase-14-worker-identity-hardening \
   --dir ./stacyvm-full-test
 ```
 
@@ -388,7 +385,6 @@ npx stacyvm-setup@latest \
     ```bash
     cd /tmp/stacyvm-npx-test
     npx stacyvm-setup@latest \
-      --branch phase-14-worker-identity-hardening \
       --dir ./stacyvm \
       --no-start
     ```
@@ -401,7 +397,6 @@ npx stacyvm-setup@latest \
 
     ```bash
     npx stacyvm-setup@latest \
-      --branch phase-14-worker-identity-hardening \
       --skip-docker-check \
       --no-start
     ```

diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
@@ -12,26 +12,18 @@ This guide gets you from a running StacyVM server to a verified sandbox workflow
 - An API key if `auth.enabled` is set in your config.
 - Python 3.9+ or Node.js 18+ if you want to use an SDK.
 
-If you have not set up a host yet, start with the [Prerequisites](/docs/getting-started/prerequisites) and [Installation](/docs/getting-started/installation) guides.
+If you have not set up a host yet, start with [Developer Onboarding](/docs/getting-started/developer-onboarding).
 
 From a source checkout, the simplest local start command is:
 
 ```bash
 make dev
 ```
 
-From npm/npx, use:
+From npm/npx, use one command:
 
 ```bash
-npx stacyvm-setup@latest \
-  --branch phase-14-worker-identity-hardening
-```
-
-To test the branch directly from GitHub instead of npm, use:
-
-```bash
-npx github:StacyOS/stacyvm#phase-14-worker-identity-hardening stacyvm-setup \
-  --branch phase-14-worker-identity-hardening
+npx stacyvm-setup@latest
 ```
 
 ## 1. Check The Server

diff --git a/index.md b/index.md
@@ -11,6 +11,9 @@ StacyVM gives your applications disposable execution environments for AI agents,
   <Card title="What is StacyVM?" icon="blocks" href="/docs/getting-started/what-is-stacyvm">
     Understand the product, use cases, advantages, and where it fits.
   </Card>
+  <Card title="Developer onboarding" icon="route" href="/docs/getting-started/developer-onboarding">
+    Run one command, verify the server, execute code, and clean up.
+  </Card>
   <Card title="Prerequisites" icon="list-checks" href="/docs/getting-started/prerequisites">
     Check the host, runtime, CLI, SDK, and production requirements before you start.
   </Card>
@@ -81,7 +84,7 @@ await client.withSandbox({ image: "node:20", ttl: "10m" }, async (sandbox) => {
 
 <Steps>
   <Step title="Install StacyVM">
-    Review [prerequisites](/docs/getting-started/prerequisites), then follow the [installation guide](/docs/getting-started/installation) for local Docker, binary, or source builds.
+    Start with [developer onboarding](/docs/getting-started/developer-onboarding), or review [prerequisites](/docs/getting-started/prerequisites) if your host needs setup.
   </Step>
   <Step title="Run the quickstart">
     Use the [quickstart](/docs/getting-started/quickstart) to validate spawn, exec, files, and cleanup.