# Development vs production environments for small teams

> A development environment keeps unreleased code, test records, and sandboxed keys isolated from the live customer data and money in production.

**A development environment isolates unreleased code, test data, and experimental configurations from production so changes cannot corrupt live customer data or interrupt paying users.** In thelastapi, every project comes with both environments already structured: production runs the live database, real payment processing, and trusted domains, while development provisions an isolated database branch with identical tables and zero rows, test-mode payments, and local auth callbacks. Small teams and AI agents can build and iterate in development without holding production secrets or risking real money.

Separating these stages prevents common operational disasters. Here is how development and production differ, why strict separation matters for small teams, and how to manage both with minimal tooling.

## What separates development from production?

Small teams often struggle with environment sprawl. Setting up parallel infrastructure across multiple third-party dashboards results in mismatched schemas, leaked credentials, and confusing test runs. 

In a unified stack, development and production share the same architecture, but operate under strict boundaries regarding data, authentication, and financial transactions. As outlined in the guide on [Keys and environments](https://thelastapi.dev/docs/keys), each thelastapi project cleanly divides these capabilities:

| Resource | Production | Development |
| --- | --- | --- |
| **Database** | Real data and live customer records | An isolated Postgres branch with matching schemas and **no rows** |
| **Sign-in** | Real user credentials; trusts verified domains | Isolated test users; trusts `http://localhost:3000` |
| **AI gateway** | The project's production key | A secondary key, metered and billed to the project |
| **Payments** | Live card payments with a 7-day hold | Test mode, test cards, no hold, `simulate` commands |
| **Company formation** | Real legal filings and fees | Sandbox mode, no charges, `simulate` commands |
| **Files** | Production storage bucket and permanent links | Isolated development storage bucket |
| **Email, Analytics, Replay** | Live mailboxes, tracking tags, and replays | **None** (local runs never send live mail or count page visits) |

Certain services deliberately do not exist in development. Hosting, web analytics, session replays, and outgoing application email do not have a development copy. Running a test suite or spinning up a local server on your laptop should never pollute your visitor metrics, record your screen as a customer replay, or blast test notifications to real customers from your live address.

## How database branching protects live data

When modifying schemas or testing migration scripts, testing directly against production tables is risky. Even read-only testing risks slow queries locking critical tables. Conversely, maintaining a manually created local SQLite or Docker database usually drifts out of sync with your live Postgres configuration.

The platform provides a serverless Postgres database for your project, but running the development workflow automatically creates an empty database branch:

```bash
# Provision the development environment and write local credentials
vibiz dev
```

This command inspects your production database schema, spins up an isolated branch matching every table, sequence, and column definition, and writes the credentials to `.env.development.local`. It contains zero customer records, giving you a clean slate. You can safely populate it with mock information, run test migrations, or alter columns without touching production records. Learn more about populating local schemas safely in our guide on how to [seed data in a development branch, not in production](https://thelastapi.dev/blog/seed-data-development-branch).

If a local experiment breaks your schema or clutters your test data, reset the branch back to a fresh mirror of production:

```bash
vibiz dev --reset
```

The next time you run `vibiz dev`, the platform provisions a fresh branch with your current production schema.

## Handling secrets, keys, and agent permissions

Environment separation is not just about the database; it is about access control. If your local environment or an automated coding agent (like Claude Code, Codex, or Cursor) holds a live API key, a mistake can delete live data or trigger unauthorized refunds.

thelastapi manages this through two distinct tiers of access keys:

1. **Full-access keys (`vz_sk_...`, `access: owner`):** Held by human owners, CI deployment pipelines, or trusted administrator sessions. These keys can view production environment variables, rotate secrets, perform live refunds, manage domains, and file companies.
2. **Limited keys (`vz_sk_...`, `access: agent`):** Built specifically for autonomous agents and external contributors. When an agent logs in via `vibiz login`, it defaults to Limited access unless explicitly elevated. 

A Limited key can create projects, trigger preview deployments, execute AI completions, and inspect development variables. However, it can **never view production secrets or move live money**. 

```bash
# Create a dedicated Limited key for a coding agent
vibiz keys create coding-agent --limited

# Inspect what a specific key can do
vibiz keys access key_123
```

When an agent holding a Limited key attempts to read production variables or execute an owner-only action, the API returns `403 forbidden` with a `details.grant_url`. The agent cannot bypass this; it must hand that URL to the project owner, who opens the console and approves the single permission (such as `database.production:read`) or denies it.

For your running application, you only need to manage a single environment variable: `VIBIZ_APP_KEY`. Read our breakdown on [VIBIZ_APP_KEY explained](https://thelastapi.dev/blog/vibiz-app-key-explained) to see how one key routes requests to the proper environment automatically.

## Payments and external services: test mode vs live money

Testing billing logic directly in production is dangerous. Making real card charges, even for small amounts, incurs fees and risks triggering fraud flags.

In development, the payment integration switches to test mode automatically. Calling `vibiz.payments.checkout` with a development key generates test checkouts that accept mock cards.

The CLI includes simulation tools so you can verify webhook handlers without making manual web requests:

```bash
# Simulate a completed payment in your development environment
vibiz payments simulate payment --amount 2500

# Simulate a dispute or a refund
vibiz payments simulate refund pay_123
```

Your application code remains identical between environments. The [@vibiz/app](https://thelastapi.dev/docs/app-sdk) client handles the differences behind the scenes:

```ts
import { vibiz } from '@vibiz/app';

// The client inspects VIBIZ_APP_KEY to determine whether to use test mode or live mode
const { url } = await vibiz.payments.checkout({
  lookup_key: 'pro-monthly',
  user: 'user_123',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
});
```

When run locally with credentials from `vibiz dev`, transactions stay in test mode. When run on your live host with your production `VIBIZ_APP_KEY`, real card payments are processed and subject to the standard 7-day hold.

## Setting up a local development workflow in practice

Small teams do not need complex orchestration scripts or multi-file environment matrices. Here is how to take a project from local development to production.

### 1. Initialize your project

Create a project directory with the resources your app needs:

```bash
vibiz init "Acme Analytics" --resources database,auth,ai
```

### 2. Start your local server

You can generate `.env.development.local` to inspect your development keys, or pass the development variables straight to your start script without writing a file:

```bash
# Run your dev server with injected development variables
vibiz dev -- npm run dev
```

If you use `@vibiz/app`, your server loads its configuration at boot time:

```ts
import { vibiz } from '@vibiz/app';

// Injects DATABASE_URL, VIBIZ_AUTH_*, and other settings into process.env
await vibiz.loadEnv();
```

Because your development environment uses isolated auth, sign-in flows will safely redirect to `http://localhost:3000` using Google or GitHub authentication without disrupting your production OAuth configuration.

### 3. Deploy to production

When your changes are tested locally, deploy them live:

```bash
# Deploy to hosting with a descriptive version tag
vibiz deploy -m "Add team invites and upgrade checkout"
```

If you need to verify changes before making them the live version, deploy a preview first:

```bash
vibiz deploy --preview
vibiz versions               # inspect past and pending deployments
vibiz promote dep_123        # promote the preview to live traffic
```

If a production deploy introduces an unexpected error, you can instantly revert the code:

```bash
vibiz rollback
```

Rolling back code updates the live site version immediately, though it does not roll back changes made to the database.

## Moving between environments without vendor lock-in

Maintaining clean boundaries between development and production makes your application portable. By avoiding proprietary environment bindings, you preserve the ability to back up or migrate your system whenever necessary.

Through the [Export](https://thelastapi.dev/docs/export) feature, you can download a complete snapshot of your code and database at any time:

```bash
# Export code, database schema, and data into a local archive
vibiz export --code --db

# Export specifically from the development environment
vibiz export --db --env development
```

A production export provides your database as an unencumbered PostgreSQL `.sql.gz` dump that can be restored into any Postgres instance using standard `psql`. Limited keys used by agents can export the code and the development database, but only full-access keys can download production data or production environment secrets.

Review [the one-API stack for indie builders](https://thelastapi.dev/blog/one-key-whole-app-stack) to see how unified architecture keeps your team agile while maintaining professional-grade isolation between your staging and live environments.

To get started, create your account at [thelastapi.dev/start](https://thelastapi.dev/start).

## Frequently asked questions

### Does running tests in a development environment cost money?

AI calls and web data actions run in development are metered and billed to the project's account balance, but database branching, test-mode payment simulations, local sign-in, and file storage during beta carry no extra platform subscription fees.

### Can an AI agent working in development access customer emails or production users?

No, agents operating with a Limited key default to the development environment, where the database branch has the same schema but zero rows, preventing any exposure to production data.

### How do I switch an app deployed on another host between development and production?

You swap the single environment variable `VIBIZ_APP_KEY`: supply the development app key during local testing or staging builds, and supply the production app key in your live host's production environment variables.

---

Published 2026-11-15 · https://thelastapi.dev/blog/development-vs-production-environments
