<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Getting Started — stack docs</title>
<meta name="description" content="Install stack, run stack setup once, and activate your first project." />
<link rel="icon" href="assets/logo.svg" type="image/svg+xml" />
<link rel="stylesheet" href="styles.css" />
<style>
.wrap { max-width: 1200px; margin: 0 auto; padding: 0 clamp(20px, 5vw, 72px); }
.nav { padding-inline: max(clamp(20px, 5vw, 72px), calc((100% - 1200px) / 2 + clamp(20px, 5vw, 72px))); }
.nav a[aria-current='page'] { color: var(--color-accent-700); }
.docs-main p, .docs-main li { font-size: 15px; }
.docs-main .lead { font-size: 17px; opacity: 0.85; max-width: 60ch; }
.step { display: flex; gap: var(--space-4); align-items: flex-start; margin: var(--space-6) 0; }
.step-num { flex: none; width: 28px; height: 28px; display: grid; place-items: center;
border: 1px solid var(--color-divider); font-family: var(--font-heading); font-size: 12px; font-weight: 600;
color: var(--color-accent-700); }
.step-body { min-width: 0; flex: 1; }
.step-body h3 { margin-top: 0; }
</style>
</head>
<body>
<nav class="nav site-nav">
<a href="index.html" class="nav-lockup"><img class="nav-mark" src="assets/logo.svg" alt="" /><span class="nav-brand">stack</span></a>
<div class="nav-links">
<a href="getting-started.html" aria-current="page">Docs</a>
<a href="changelog.html">Changelog</a>
<a href="https://github.com/sanayasfp/stack" target="_blank" rel="noopener">GitHub</a>
</div>
<button type="button" class="btn btn-secondary btn-icon theme-toggle blueprint" id="theme-toggle" aria-label="Switch between light and dark">
<i class="corner tl"></i><i class="corner tr"></i><i class="corner bl"></i><i class="corner br"></i>
<svg class="icon-sun" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/></svg>
<svg class="icon-moon" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
</button>
</nav>
<div class="wrap docs-layout">
<aside class="docs-side">
<div class="side-group">
<h6>Guide</h6>
<a href="getting-started.html" aria-current="page">Getting Started</a>
</div>
<div class="side-group">
<h6>Reference</h6>
<a href="manifest.html">Manifest (stack.toml)</a>
<a href="cli.html">CLI Commands</a>
</div>
<div class="side-group">
<h6>More</h6>
<a href="https://github.com/sanayasfp/stack/tree/main/examples" target="_blank" rel="noopener">Examples</a>
<a href="changelog.html">Changelog</a>
<a href="https://github.com/sanayasfp/stack" target="_blank" rel="noopener">GitHub</a>
</div>
</aside>
<main class="docs-main">
<span class="kicker" style="display:block;font-family:var(--font-heading);font-size:12px;letter-spacing:.08em;text-transform:uppercase;font-weight:600;color:var(--color-accent-700);margin-bottom:8px;">Guide</span>
<h1>Getting Started</h1>
<p class="lead">stack runs your project's languages, databases, and dev server as plain processes and routes a real local domain to whichever one you're working on — no containers, no idle hypervisor, nothing running you didn't ask for.</p>
<div style="display:flex; gap:var(--space-2); flex-wrap:wrap; margin: var(--space-3) 0 var(--space-6);">
<span class="tag tag-accent">Windows — PowerShell & cmd</span>
<span class="tag tag-outline">macOS — coming soon</span>
<span class="tag tag-outline">Linux — coming soon</span>
</div>
<h2 id="install">1. Install</h2>
<p>Pick whichever you already use:</p>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">winget</span></div>
<pre class="term-body"><span class="term-prompt">$</span> winget install stack.cli</pre>
</div>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">scoop</span></div>
<pre class="term-body"><span class="term-prompt">$</span> scoop bucket add stack https://github.com/sanayasfp/scoop-bucket
<span class="term-prompt">$</span> scoop install stack</pre>
</div>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">chocolatey</span></div>
<pre class="term-body"><span class="term-prompt">$</span> choco install stack</pre>
</div>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">cargo</span></div>
<pre class="term-body"><span class="term-prompt">$</span> cargo install stackenv</pre>
</div>
<p style="font-size:13px;opacity:0.75;">The crate is published as <code>stackenv</code> (<code>stack</code> was already taken on crates.io by an unrelated project) — it still installs a <code>stack</code> command.</p>
<h2 id="setup">2. Run <code>stack setup</code></h2>
<p>One command, once. It wires the shell hook into your PowerShell profile (so activation runs on every prompt) and installs the three tools stack delegates to — <a href="https://github.com/version-fox/vfox" target="_blank" rel="noopener">vfox</a>, <a href="https://github.com/astral-sh/uv" target="_blank" rel="noopener">uv</a>, and <a href="https://caddyserver.com" target="_blank" rel="noopener">Caddy</a> — at the pinned versions stack is built and tested against.</p>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">powershell</span></div>
<pre class="term-body"><span class="term-prompt">$</span> stack setup
added the stack hook for pwsh
checking vfox/uv/caddy...
vfox: OK (1.0.11)
uv: OK (0.11.7)
caddy: OK (2.11.4)
tip: for curl/Postman/non-browser clients to also resolve *.localhost, consider
Acrylic DNS Proxy (optional, one-time, needs admin rights)</pre>
</div>
<p>Restart your terminal (or reload <code>$PROFILE</code>) once, so the new hook takes effect in the current session.</p>
<h2 id="first-project">3. Create a project</h2>
<div class="step">
<span class="step-num">1</span>
<div class="step-body">
<h3>Scaffold a manifest</h3>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">powershell</span></div>
<pre class="term-body"><span class="term-prompt">$</span> stack new acme-api
domain: acme-api.localhost
Add a language? yes
language name (e.g. php, node, python): php
version: 8.3.1
Add a language? no
Add a service? yes
service name (e.g. mysql, postgres, mongo): mysql
version: 8.0.35
Add a service? no
created acme-api\stack.toml
next: cd into it, add a [run] command when you know it, then `stack up`</pre>
</div>
<p><code>stack new</code> prompts you through it interactively and writes a commented <code>stack.toml</code>. You can also hand-write one — see the <a href="manifest.html">Manifest Reference</a>.</p>
</div>
</div>
<div class="step">
<span class="step-num">2</span>
<div class="step-body">
<h3>Add how it runs</h3>
<p>Open <code>stack.toml</code> and set <code>[run]</code> — the one process that needs a stable URL, usually your app's own dev server:</p>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">acme-api/stack.toml</span></div>
<pre class="term-body">[run]
command = "php -S 127.0.0.1:{port} -t public"</pre>
</div>
</div>
</div>
<div class="step">
<span class="step-num">3</span>
<div class="step-body">
<h3>Bring it up</h3>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">acme-api — stack up</span></div>
<pre class="term-body"><span class="term-prompt">$</span> cd acme-api
<span class="term-prompt">$</span> stack up
Loaded C:\Users\you\acme-api\stack.toml
project: acme-api
domain: acme-api.localhost
languages: ["php"]
services: ["mysql"]
php: C:\Users\you\.vfox\cache\php\v-8.3.1\...\php.exe -> PHP 8.3.1 (cli)
service.mysql: started (pid 41232, port 3306)
schema 'acme_api' — automatic creation not yet implemented; create it manually if needed
run: php -S 127.0.0.1:52140 -t public (pid 41244, port 52140)
log: C:\Users\you\.stack\logs\acme-api.log
routed: http://acme-api.localhost -> 127.0.0.1:52140</pre>
</div>
</div>
</div>
<h2 id="ambient">4. Everyday use</h2>
<p>Once <code>stack setup</code> has run, activation is ambient — no daemon to remember to start. <code>cd</code> into any folder with a <code>stack.toml</code> and your pinned <code>php</code>/<code>node</code>/<code>python</code> are already first on <code>PATH</code>, for anything you run by hand: <code>composer install</code>, <code>npm install</code>, a test runner. Leave the folder and <code>PATH</code> resets. You only need <code>stack up</code> for the one process that needs a real routed domain and needs to keep running without a terminal watching it.</p>
<p>When you're done for the day:</p>
<div class="blueprint term">
<div class="term-bar"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span><span class="term-name">powershell</span></div>
<pre class="term-body"><span class="term-prompt">$</span> stack down --all</pre>
</div>
<p>Stops every project process and every shared service — the actual 0% CPU point, not just the one project you were looking at.</p>
<h2 id="next">Next</h2>
<p><a href="manifest.html">Manifest Reference</a> — every <code>stack.toml</code> field, with defaults. <a href="cli.html">CLI Reference</a> — every subcommand. <a href="https://github.com/sanayasfp/stack/tree/main/examples" target="_blank" rel="noopener">Examples</a> — four real projects (FastAPI, Node, React, Laravel), each showing a different part of the manifest instead of the same happy path four times.</p>
</main>
</div>
<script src="site.js"></script>
</body>
</html>