Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Installing Spree"
sidebarTitle: Installation
description: "Try Spree in a free hosted sandbox, or install it locally, run your first store, and deploy it to production with the official starter template."
---
<Tip>
**Just want to try Spree?** [Launch a free sandbox](https://console.spree.sh) — a hosted Spree store with the admin dashboard and APIs, ready in your browser. Nothing to install. See [Trying Spree in a sandbox](#trying-spree-in-a-sandbox).
</Tip>
## Using `create-spree-app`
The quickest way to get started. Scaffolds a full Spree project with React admin dashboard and Next.js Storefront (optional).
**Requirements:** [Node.js](https://nodejs.org/) 24+ with npm 9+, and [Docker](https://docs.docker.com/get-docker/) running. Seeing an npm error before setup starts? See [Troubleshooting](/developer/create-spree-app/quickstart#troubleshooting).
```bash
npx create-spree-app@latest my-store
```
The CLI walks you through an interactive setup where you choose the project name and whether to include the Next.js Storefront. It then builds a Docker stack with Postgres, and Spree API.
Once complete it will open a browser window so you can finalize the store setup (pick name, currency, your email/password).
<Frame caption="Setting up your first store">
<video autoPlay muted loop playsInline controls className="block w-auto max-w-full h-auto rounded-xl" src="/videos/store-setup.mp4"></video>
</Frame>
## Trying Spree in a sandbox
A [Spree sandbox](https://console.spree.sh) is a free, hosted Spree store at its own `*.spree.sh` address. Use it to explore the admin dashboard, try the APIs, or point a storefront at it — without installing Node.js, Docker or Ruby.
1. Sign in at [console.spree.sh](https://console.spree.sh) and click **Create store**.
2. Click **Open** to go to its admin dashboard and manage products, orders and settings.
3. To call the Admin API, create a secret key under **Settings → API Keys** and use it with the [Spree CLI](/developer/cli/admin-api#use-with-a-sandbox) or the [Admin SDK](/developer/sdk/admin/quickstart).
When you're ready to customize Spree's code, install it locally with `create-spree-app`.
## Project structure and overview
`create-spree-app` creates a project folder like this:
```
my-store/
├── server/ # The Spree API
├── apps/
│ ├── dashboard/ # Admin dashboard (Vite/React)
│ ├── seller-dashboard/ # Seller panel, for marketplaces (Vite/React)
│ └── storefront/ # Next.js storefront (if selected)
├── .env # Ports, secrets and service URLs
├── .spree/ # CLI credentials — gitignored, created on first run
├── docker-compose.yml # The local stack
├── package.json # Scripts and the pinned @spree/cli
├── AGENTS.md # Instructions for coding agents
├── CLAUDE.md # Imports AGENTS.md for Claude Code
└── README.md # How to run everything
```
## Using the Spree CLI
Projects scaffolded with `create-spree-app` include [`@spree/cli`](/developer/cli/quickstart) for managing the backend and calling the Admin API. Because it's a project dependency, run it with `npx` (or any package-manager script):
```bash
npx spree dev # boot the Docker stack
npx spree api get products # query the Admin API (read-only key preconfigured)
```
Project setup mints a read-only Admin API key into `.spree/credentials.json` (and `spree api` mints it on first use if you skipped setup), so `spree api` works without any extra configuration.
To call `spree` directly without the `npx` prefix, install the CLI globally:
```bash
npm install -g @spree/cli
spree api get products
```
See the [Spree CLI guide](/developer/cli/quickstart) for all commands and the [Admin API from the CLI](/developer/cli/admin-api) for querying your store's data.
## Next Steps
<Card title="How Spree fits together" icon="brain" href="/developer/core-concepts/architecture" horizontal>
The catalog, the cart, the order and fulfillment — what each one is for, and the two APIs you build against. Twenty minutes here saves a lot of guessing later, and it ends by pointing you at whichever path suits you.
</Card>
In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js Storefront](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [API reference](/api-reference/admin-api/introduction) to see what you can do with the Admin API.
<Tip>
Using an AI coding agent? `create-spree-app` installs the [Spree agent skills](/developer/agentic/agent-skills) and connects your agent to the [docs MCP server](/developer/agentic/docs-mcp) unless you said no — if you skipped them, run `npx spree add ai` in your project. Your agent then knows the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).
</Tip>
---
Congrats! You've set up your Spree application and it's looking amazing!
Give Spree a [GitHub Star](https://github.com/spree/spree)<Icon icon="star" iconType="solid" color="#FFD43B" />, why don't ya? Thank you for supporting Spree open-source! <Icon icon="heart" iconType="solid" color="#FF0000" />
Need support or want to give some feedback? Join our [Discord](https://discord.spreecommerce.org/)