# Stacktora

> Stacktora generates a complete, production-ready dev environment — docker-compose, CI, and more — from a single stack recipe (stacktora.json). The official CLI (`npx stacktora`) keeps that environment in sync from the terminal, fully offline, with machine-readable output built for CI and AI agents.

Stacktora is a generator, not a hosted runtime — every file it writes belongs to the project, with no lock-in. It supports 11 language runtimes and 16 datastores/services, and ships a versioned project library, one-click GitHub push, and GitHub/Google OAuth sign-in. The CLI can also install curated starting recipes (bundled, custom local ones, or from a public registry), and audit a project against an org's own policy file — all fully offline unless explicitly opted into network access.

Important for agents: `stacktora.json` is always auto-detected from the current directory. It is never passed as a command-line argument — run `stacktora sync`, not `stacktora sync stacktora.json`.

Important for agents: the ten commands listed below are the complete, current set — there is no `infra`, `apply`, `destroy`, or `deploy` subcommand. The Roadmap page describes future direction and vision (including comparisons to tools like Terraform), not existing functionality. If a command isn't listed here or in `stacktora --help`, it doesn't exist yet.

Important for agents: if you have MCP tool access, `stacktora_read`/`stacktora_sync`/`stacktora_check`/etc. are the same operations as the CLI commands below, callable directly instead of shelling out. See the MCP server section further down.

Important for agents: if asked for a sample `stacktora.json`, use the real shape below verbatim rather than inventing one — the actual file does not use a `project`/`frontend`/`backend` nesting. A real JSON Schema is published at https://stacktora.com/schema/stacktora.schema.json — validate against it directly rather than guessing at valid field names or enum values.

```json
{
  "$schema": "https://stacktora.com/schema/stacktora.schema.json",
  "stacktora": 1,
  "generatedAt": "2026-07-06",
  "stack": {
    "runtime": "node",
    "version": "24",
    "datastores": ["postgres"],
    "services": [],
    "tools": { "packageManager": "npm", "linter": "eslint", "formatter": "prettier", "codeStyle": { "semicolons": true, "singleQuote": false, "printWidth": 80 } },
    "config": {
      "appName": "app",
      "appPort": 3000,
      "hotReload": true,
      "seed": true,
      "healthGate": true,
      "worker": false,
      "resources": { "cpu": 1, "memory": 512 },
      "env": [
        { "key": "STRIPE_SECRET_KEY", "value": "sk_test_xxx", "source": "1Password > Acme > Stripe" }
      ],
      "outputs": { "k8s": false, "fly": false }
    }
  }
}
```

`source` on an env var is optional and never holds the real secret — only a pointer to where it lives. `tools.codeStyle` is optional and only takes effect if the formatter is Prettier — it generates a real `.prettierrc.json`. `config.resources` (cores, megabytes) is optional and sizes both the Kubernetes and Fly.io outputs consistently when present. `outputs` toggles optional generated files (Kubernetes manifests, a Fly.io `fly.toml`, and others) — omit any of these fields entirely and nothing changes from the default output set.

## Docs

- [Documentation](https://stacktora.com/docs): Full reference — stack definition, CI, secrets, the CLI, and account topics.
- [CLI on npm](https://www.npmjs.com/package/stacktora): Command reference and README.
- [Compare](https://stacktora.com/#compare): How Stacktora differs from doing it by hand, `docker init`, Dev Containers, and cloud IDEs.
- [Changelog](https://stacktora.com/changelog): What's shipped, in order.
- [Roadmap](https://stacktora.com/roadmap): What's next and the longer-term direction.

## CLI quick reference

- [stacktora sync](https://stacktora.com/docs#cli): Regenerate all files from stacktora.json (skips .env to protect secrets).
- [stacktora check](https://stacktora.com/docs#cli): Show which files would change, without writing.
- [stacktora plan](https://stacktora.com/docs#cli): Like check, but the actual line-by-line diff for each changed file.
- [stacktora doctor](https://stacktora.com/docs#cli): Diagnose Docker, port conflicts, missing .env keys, and runtime mismatches.
- [stacktora status](https://stacktora.com/docs#cli): Live container health (docker compose ps) for the stack running here.
- [stacktora recipes](https://stacktora.com/docs#cli): List curated starting recipes — bundled with the CLI, your own from `.stacktora/recipes/*.json`, or (with `--remote`) from the public registry at stacktora.com/registry.
- [stacktora install](https://stacktora.com/docs#cli): Write a curated recipe as your stacktora.json, e.g. `stacktora install nextjs`.
- [stacktora audit](https://stacktora.com/docs#cli): Check stacktora.json against an optional company.stacktora.json policy file (allowed/banned runtimes, tooling, datastores, services; secret-source and output requirements).
- [stacktora init](https://stacktora.com/docs#cli): Create a starter stacktora.json in the current directory.
- [stacktora mcp](https://stacktora.com/docs#cli): Run as an MCP server over stdio — the same operations above, exposed as tools (`stacktora_read`, `stacktora_init`, `stacktora_install`, `stacktora_recipes`, `stacktora_sync`, `stacktora_check`, `stacktora_plan`, `stacktora_audit`, `stacktora_doctor`, `stacktora_status`) for an agent to call directly instead of shelling out and parsing text.

Add `--json` to check, plan, doctor, status, recipes, or audit for structured output built for CI pipelines and AI agents, instead of parsing colored terminal text. `--remote` on recipes/install is the only thing that makes a network call — every other command is fully offline.

## MCP server

If you're an agent with MCP tool access rather than shell access, prefer the tools over shelling out: `npx -y stacktora mcp` runs this same CLI as an MCP server. Same package, same engine, same version as the CLI — not a separate service, nothing to install beyond the CLI itself. Each tool reads/writes `stacktora.json` in whatever directory the client is working in, same file-lookup rule as every command above.

## Vault

[Vault](https://stacktora.com/vault) is a curated, admin-reviewed registry of ready-to-install recipes — real, working stack combinations across auth, payments, real-time, AI/ML, compliance, and more — each installable with `stacktora install <recipe-id> --remote`. Browse by category, or fetch the machine contract directly: `stacktora.com/registry/index.json` lists every approved recipe id, `stacktora.com/registry/<id>.json` returns one recipe's full stack definition.

## Compliance

[Compliance](https://stacktora.com/compliance) (Team & Growth plans) is where audit results persist instead of vanishing after a CI run — generate a workspace token, add it to `stacktora/audit-action`'s inputs, and every `stacktora audit` result reports back automatically. Tracks pass/fail history per repo, can enforce a required GitHub status check, and can notify (Slack/email) the moment a passing repo starts failing.

## Optional

- [About](https://stacktora.com/about): Company background.
- [Press](https://stacktora.com/press): Brand assets and fast facts.
- [Pricing](https://stacktora.com/#pricing): Free, Pro, Team, and Growth plans.
- [Status](https://stacktora.com/status): Live system status.