# 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 nine 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 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.

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.

## 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.