From 16ae92f9e9e1db993fbdea9ef01c1c04cff4f134 Mon Sep 17 00:00:00 2001 From: ARPAN MONDAL Date: Mon, 11 May 2026 19:46:55 +0530 Subject: [PATCH] docs: simplify developer onboarding --- docs.json | 1 + docs/getting-started/developer-onboarding.mdx | 179 ++++++++++++++++++ docs/getting-started/installation.mdx | 10 +- docs/getting-started/prerequisites.mdx | 9 +- docs/getting-started/quickstart.mdx | 14 +- index.md | 5 +- 6 files changed, 190 insertions(+), 28 deletions(-) create mode 100644 docs/getting-started/developer-onboarding.mdx diff --git a/docs.json b/docs.json index 5b76b21..9495bea 100644 --- 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 new file mode 100644 index 0000000..2f9514f --- /dev/null +++ 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`. + + + 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. + + +## 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 + + + + 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. + + + + Install Go, then rerun setup. + + macOS: + + ```bash + brew install go + ``` + + Ubuntu or Debian: + + ```bash + sudo apt update + sudo apt install -y golang-go + ``` + + + + Check what is listening: + + ```bash + lsof -iTCP:7423 -sTCP:LISTEN + ``` + + Stop that process, or use the StacyVM server that is already running. + + + + 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 + ``` + + + +## 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 index 63db2bd..6f9fdba 100644 --- 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 index fd53593..6d7aced 100644 --- 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 index 7d4f56a..8941320 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -12,7 +12,7 @@ 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: @@ -20,18 +20,10 @@ From a source checkout, the simplest local start command is: 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 index b44b668..434876e 100644 --- a/index.md +++ b/index.md @@ -11,6 +11,9 @@ StacyVM gives your applications disposable execution environments for AI agents, Understand the product, use cases, advantages, and where it fits. + + Run one command, verify the server, execute code, and clean up. + Check the host, runtime, CLI, SDK, and production requirements before you start. @@ -81,7 +84,7 @@ await client.withSandbox({ image: "node:20", ttl: "10m" }, async (sandbox) => { - 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. Use the [quickstart](/docs/getting-started/quickstart) to validate spawn, exec, files, and cleanup.