Skip to content
stack
Get started
Help

FAQ

The honest answers. Pre-alpha caveats, the Phantom requirement, OAuth app status, and what happens when things go sideways.

Is this production-ready?

No — Stack is v0.1, pre-alpha. Interfaces are still moving, error messages are still being hardened, and some providers have paste-a-token fallbacks because their OAuth apps aren't registered yet (see below). We use it internally every day and it works end-to-end; we wouldn't recommend it for a team of 50 in its current state.

The data model (two-file .stack.toml split, Phantom-gated secrets, MCP wiring) is stable. The CLI surface will add commands but won't remove them. Breaking changes will land in the 0.x window and stop at 1.0.

Why is Phantom required?

Because Stack otherwise has nowhere to put your secrets except .env on disk. That's the thing we're specifically trying to avoid. Phantom gives us an encrypted vault, a uniform way to reveal secrets at exec time, and a clean story for syncing secrets to CI.

If you have an existing secret manager (1Password, Doppler, Infisical), we'd rather integrate Phantom with it than compete — Phantom Cloud is designed to be the last-mile layer, not the source of truth. That work isn't in v1 yet. For now: Phantom on every machine that runs stack add.

Which providers still fall back to paste-a-token?

Registering an OAuth app with a provider takes a week to a month, depending on who answers first. The following providers currently use a personal-access-token paste instead of full OAuth:

  • Neon, Turso, Vercel, Cloudflare, Sentry — PAT paste with automated verification.
  • Railway, Fly.io, Render, Upstash, Convex, Linear, Resend, PostHog, Clerk, Stripe, OpenAI, Anthropic, xAI, DeepSeek — API key paste.
  • Firebase — service-account JSON paste.
  • AWS — IAM access key pair paste.

OAuth (PKCE or device flow) is live for Supabase and GitHub. Expect steady migration as our OAuth apps get registered with each provider — the API contract for providers is authKind: "api_key" | "pat" | "oauth_pkce" | "oauth_device", so the CLI surface doesn't change when a provider moves from paste to OAuth.

Does Stack touch the internet without asking?

Yes, during these commands (and only these):

  • stack add — logs into the provider, creates an upstream resource, fetches credentials.
  • stack doctor — hits each provider's API to verify the stored credential still works.
  • stack upgrade — pings the npm registry to check for a newer @ashlr/stack.
  • stack login — refreshes OAuth / PAT credentials.
  • stack sync — pushes secrets to Vercel / Railway / Fly.
  • stack clone — git clones the specified URL, then scans locally.

Zero telemetry. Stack never calls home. No analytics, no usage pings. Run it with Wireshark open if you want to verify.

What happens if I delete .stack.toml?

Your upstream resources stay exactly as they were. Stack would just lose its map of what it had wired. The secrets in Phantom also stay put. You'd see "no services configured" on stack status; running stack init again would start fresh.

To actually tear things down, use stack remove <service> (deprovisions upstream + removes the secrets + cleans up .mcp.json) or stack remove --all --keepRemote (removes local state only).

Can I commit .env.local with phm_ tokens?

Technically yes — a phm_ token is a meaningless placeholder without the vault. But we don't recommend it; the community is still learning to recognise Phantom tokens on sight, and a leaked token combined with a leaked passphrase is worse than nothing. Add .env.local to .gitignore and keep the vault story clean.

How do I use Stack with a monorepo?

Each .stack.toml is per-project, and most monorepos want one stack per app (marketing site, dashboard, worker all have different services). Run stack init inside each app directory. The cross-project registry (stack projects list) will show each one, and stack doctor --all will run healthchecks across the whole machine.

Shared secrets (e.g. one DATABASE_URL used by every app) stay in one Phantom vault — Phantom is machine-wide, not per-project — so de-duping just works. Declare the same secret slot name in each .stack.toml.

What does stack doctor --fix actually do?

For each service with a failing healthcheck, Stack asks before re-running stack add. That may kick off a browser OAuth dance or provision a new resource on your behalf, so we force an interactive confirm. Declining is always safe; the service stays marked as broken and you can fix it by hand.

Why not just use .env files like everyone else?

Nothing stops you. Stack's job is to collapse the 45-minute "tab-hop to create these 8 services, then copy 20 keys into .env" step into one command. If your project has one API key and no MCPs, you don't need Stack.

Stack earns its keep when (a) your stack has 5+ services, (b) two or more of them have MCP servers worth wiring, or (c) you're onboarding someone new and don't want to write a wiki page about where every key lives.

Can I use a template without its MCP servers?

Yes. Apply the template, then edit .stack.toml and remove the mcp = "…" line for services you don't want Claude / Cursor to reach into. On the next stack add or stack remove, .mcp.json gets regenerated accordingly. Alternatively, edit .mcp.json directly — Stack only rewrites entries for services it manages.

Where does Stack store OAuth access tokens?

In Phantom, under a per-provider slot name (e.g. SUPABASE_STACK_PAT, GITHUB_TOKEN). That means your provider auth is subject to the same E2E encryption as your application secrets. Clear them with phantom remove <slot> if you want to force a fresh OAuth.

How do I uninstall Stack?

# optionally: deprovision everything Stack created
stack remove --all

# uninstall the CLI
bun remove -g @ashlr/stack   # or: npm uninstall -g @ashlr/stack

# drop the global state (registry only — does NOT touch Phantom)
rm -rf ~/.stack/

# Phantom is a separate install; leave it alone unless you also want
# to nuke every secret, in which case:
#   phantom remove --all   (interactive confirmation)

Where do I report bugs / request providers?

github.com/ashlrai/ashlr-stack/issues. Provider requests are most useful when they include: the secret slots you'd expect, whether the provider has an API for creating resources (upstream provisioning) or only an API for reading them, and whether there's an existing MCP server worth wiring.