Local development
For citizen developers
Between your first prompt and a deployed app, your agent builds and runs the app on the machine it’s working from — usually so it can see the app render, exercise a feature, and check it against real data before opening a pull request. This page explains how that local loop works. You don’t run any of it yourself; it’s here so you understand what your agent is doing and why it never needs a credential on the laptop.
The short version: your agent talks to the same governed Greenlight your deployed app does. Data sources stay live and brokered exactly as they are in production, the app’s own database runs as a throwaway local copy, and no secret value ever reaches the laptop through the agent.
Pairing the CLI, once
Section titled “Pairing the CLI, once”Greenlight ships a small command-line tool — the greenlight CLI — bundled inside the same plugin that connects your agent. Your agent signs it in once: it runs greenlight pair, which prints a short code, and approves that code over the agent’s existing Greenlight session — no browser, no second sign-in. (If the agent has no working Greenlight session, greenlight login does the same thing through a one-time browser sign-in instead.) Either way the CLI inherits your identity — everything it does locally is attributed to you, the same as everything else your agent does in Greenlight.
After sign-in, the CLI holds its own revocable Greenlight credential — not an upstream secret, just proof of who’s asking. It refreshes itself so your agent isn’t forced to stop and re-authenticate mid-build, and IT deactivating you cuts it like every other session. It’s the only standing credential on the machine.
Running the app
Section titled “Running the app”To run the app, the agent uses one command:
greenlight run --app <app_id> -- npm run dev(The part after -- is whatever the app’s normal dev command is; --app names the app so the run uses the app’s grants — the exact access it will have in production.) A few things are worth knowing about what this does:
- There’s no local server and no file on disk. The CLI resolves the app’s environment from Greenlight at run time and injects the values straight into the running process. Nothing is written to a
.envfile — there’s no credentials file for anyone to leak or forget to delete. - The app code is identical to what deploys. Locally and in production, the app reads the same environment variable names; only the values behind them differ. The one rule the agent follows is to read those variables rather than hardcode any URL or key.
- The mode is always explicit. Without
--app, the run uses your personal grants instead (below) — and if the agent forgets the flag inside an app checkout, the CLI says so on startup rather than silently switching whose access is in play.
How each kind of dependency behaves locally
Section titled “How each kind of dependency behaves locally”What your app touches falls into a few kinds, and each behaves a little differently when the app runs locally.
Proxied integrations — live, through the same broker
Section titled “Proxied integrations — live, through the same broker”Most data sources your app reaches — Slack, a CRM, a REST API — are proxied: the app calls a Greenlight URL and the broker swaps in the real credential at the edge. Locally, this works exactly as it does in production. The app calls the same public proxy URL the deployed app uses, authenticated with a short-lived token the CLI mints from your paired session — scoped to this one app and to you.
The upstream secret stays inside Greenlight; the laptop never holds it. Every local call is brokered, authorized against the same grants, and audited under your name, just like a production call.
Injected credentials — raw, in-process, only when IT allows it
Section titled “Injected credentials — raw, in-process, only when IT allows it”A few credentials can’t be carried by an HTTP proxy — a database connection string, a binary protocol, an SDK that builds its own connection. Greenlight delivers those by injecting the value into the app’s environment. Locally, greenlight run delivers that raw value into the running process — but only when IT has turned on local access for that specific credential. When IT hasn’t, the agent works against fixtures instead (see below). Either way the value lives only in the running process, never in a file.
The app’s own database — a local fixture, plus inspection of real data
Section titled “The app’s own database — a local fixture, plus inspection of real data”Your app’s own database isn’t reached live from the laptop. Instead the agent runs a local fixture database — a throwaway copy with the app’s schema and made-up data — so it can build and test freely without touching real records.
When the agent needs to see what’s actually in the deployed database — to reproduce a bug, to understand the shape of real data — it doesn’t connect to it. It uses the always-on inspection tools below, which run inside Greenlight and return only results.
Blob storage — short-lived access
Section titled “Blob storage — short-lived access”If your app stores files, the agent gets time-limited access to the storage container for the run — access that expires on its own. As with everything else, there’s no standing key on the machine.
Inspecting real data, safely
Section titled “Inspecting real data, safely”To investigate real, deployed data without ever pulling a credential onto the laptop, the agent has three inspection tools that run inside Greenlight and return only results:
| Tool | What it does |
|---|---|
| inspectAppDb | Runs a read-only query against your app’s deployed database and returns the rows. |
| inspectIntegrationApi | Makes a single request against a granted integration and returns the response. |
| inspectAppBlob | Lists or reads files in your app’s storage container. |
These are always available for your app’s own database and storage and for any integration the app has been granted — there’s no toggle to flip. They execute against the real, vaulted credential on Greenlight’s side and return results, never the credential itself, so the agent can debug against production data without that data’s keys ever leaving the platform. Every inspection is read-only, size-capped, and logged under your name in the audit log.
This is how an agent reproduces “it works in the fixture but breaks on the real data” without anyone handing it a database password.
Personal access — real data with no app at all
Section titled “Personal access — real data with no app at all”Sometimes the thing you want isn’t an app: a one-off analysis script, a notebook, a quick visualizer over company data you may never ship. You don’t need to register an app, create a repo, or merge anything for that. Your agent requests access for you, personally:
- It calls
requestCredentialAccessnaming the integration and credential (and why). If IT set that credential to auto-approve, access is granted on the spot; otherwise the request lands in IT’s review queue and your agent tells you it’s pending. - Once granted,
greenlight run -- <cmd>— with no--appflag — runs your script against your own granted integrations, through the same governed proxy. The credential still never touches the laptop for proxied integrations, and every call is audited under your name.
Your personal access and an app’s access are separate: an app never runs on your grants, and your grants never activate anything for an app. When a personal script grows into something worth sharing, the agent registers it as a real app and declares the app’s own access in its manifest.
What’s live versus fixture-only follows the grant
Section titled “What’s live versus fixture-only follows the grant”A granted integration is live locally — the grant is what IT approved, and it carries local development with it:
- Proxied integrations are live through the same governed proxy the deployed app uses; the credential never touches the laptop.
- Injected integrations deliver their real value into the running process — that’s what injected delivery means, and IT knew it when the integration was registered and when the grant was approved. Every delivery is recorded in the audit log under your name.
- User-delegated sources (where the upstream sees you, not an app) can’t run on a laptop yet — the agent works against fixtures it writes itself, and still investigates the real source through the inspection tools.
The local experience is governed the same way everything else is: by what IT has approved. If your agent says it’s using sample data for a source, the grant hasn’t been approved yet (or the source is user-delegated) — a question for IT, not something to change in the app.