thelastapi
Get started free

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.

On this page 7 sections

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, each thelastapi project cleanly divides these capabilities:

ResourceProductionDevelopment
DatabaseReal data and live customer recordsAn isolated Postgres branch with matching schemas and no rows
Sign-inReal user credentials; trusts verified domainsIsolated test users; trusts http://localhost:3000
AI gatewayThe project's production keyA secondary key, metered and billed to the project
PaymentsLive card payments with a 7-day holdTest mode, test cards, no hold, simulate commands
Company formationReal legal filings and feesSandbox mode, no charges, simulate commands
FilesProduction storage bucket and permanent linksIsolated development storage bucket
Email, Analytics, ReplayLive mailboxes, tracking tags, and replaysNone (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:

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

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

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

Terminal
# 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 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:

Terminal
# 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 client handles the differences behind the scenes:

TypeScript
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:

Terminal
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:

Terminal
# 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:

TypeScript
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:

Terminal
# 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:

Terminal
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:

Terminal
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 feature, you can download a complete snapshot of your code and database at any time:

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

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.