When you need this
Most of the time Ship runs against the workspace cloud — your console talks to the workspace API, the routines run against your tracker, the audit log is in one place. That is the right shape for an everyday team.
There are a few moments when the right shape is the other one: the whole stack on one laptop, no network round-trip, no shared services.
- You are demonstrating Ship to a customer in a room without trusted internet — a regulated client site, a sales meeting with strict device policy, a conference Wi-Fi you do not want to bet on.
- You are testing a new routine in isolation and want to be certain it cannot affect production tracker state, even by accident.
- Your pilot is in a sector where the first round of data needs to stay on-prem until procurement is finished.
- You are an engineer in transit on a flight and you want the console to actually respond.
The local sandbox is the profile that covers those cases. It is the same Ship — same console, same workflows, same artifacts — running against a database on your machine and a set of in-memory stand-ins for the integrations that would normally call out.
What you get
When you run the sandbox you get the full surface area locally — the console, the workspace API, a local database seeded with a dev workspace and a dev user, the knowledge base, the audit log, the analytics pages. Tracker, code host, and CI are simulated locally so nothing reaches out.
What you do not get is a line back to a real workspace. The sandbox is its own world. Anything you publish, route, or audit inside it stays inside it. That is the property you wanted.
Bringing it up
The reference flow is two commands.
First, copy the shared environment file. The repo ships with a .env.shared that pins the sandbox profile — local database, local API base URLs, local-auth mode, the memory adapters. Copy it to .env (or source it, depending on your shell preference) and you have the configuration in place. Edit the file if you need to change ports, override the seed user, or pin a particular bundle version.
Second, bring the stack up:
make dev-up
make dev-up starts the local Postgres container, applies migrations, runs the dev seed (creating a workspace and a dev@localhost user that you sign in as), and starts the backend and the console with hot-reload. The first run takes a minute or two because of the migrations; subsequent runs are fast.
Once it is up, open the console at http://localhost:3000 and sign in. You are now in the local sandbox.
Stop the stack with make dev-down when you are finished. The database persists between runs by default — the workspace you set up is still there in the morning. If you want a clean slate, make dev-db-reset drops the database and re-seeds.
What is real and what is simulated
The database is real. The console is the same application your team uses every day. The audit log records the same actions. What is simulated lives at the seams — instead of calling Linear, GitHub, or your CI, the sandbox uses in-memory stand-ins that speak the same shape. You can author tickets, move them through the workflow, watch routines respond — all without a network packet leaving the laptop.
The practical limit: the stand-ins do not know about your real repos, real teams, or real members. They cover the shapes of the integrations, not their content. If you want to demo Ship reading from a real repo, you need the network. If you want to demo Ship orchestrating a routine end-to-end without external calls, the sandbox is exactly right.
When the sandbox is the wrong choice
A handful of cases where you should reach for a real workspace instead:
- A pilot that needs to outlive the laptop. The sandbox state lives on one machine. If the pilot is going to run for two months and three people need to use it, run a real cloud workspace and give it a strict scope.
- A customer who wants to evaluate your knowledge base. The sandbox knowledge base is seeded with demo content. You can author into it, but the value of Ship is what your knowledge base shows; that requires a real workspace.
- Anything that depends on the workspace's analytics over weeks. DORA needs a real change stream to produce real numbers. A sandbox can show you the page, not a real reading.
The sandbox is a tool for bounded, contained, repeatable situations. Use it for those. For everything else, use the real workspace.
Hand-off back to the engineer
Setting up the sandbox is a five-minute task for an engineer who has the repo cloned, Node 20 installed, Docker available, and a healthy disposition toward make targets. If you are the product owner reading this, the right move is to forward this page to whoever does that kind of thing on your team, schedule fifteen minutes with them, and watch the console come up on your laptop. From there, the rest of the manual works exactly the same.