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.

Signing the CLI in, 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, by running greenlight login.

Most of the time you barely see it. If the agent is running on your own machine, login opens your default browser. When that browser is already signed in to Greenlight, a tab flashes through to a “you’re signed in” page and your agent carries on — nothing to type, nothing to read. If you’re signed out, the tab lands on your organization’s sign-in screen; finish it there if you’re quick, but a first-time sign-in, a two-factor prompt, or a passkey usually takes longer than the CLI waits, and that’s fine — it moves on to the code below. Completing that browser step also signs the same browser into the Greenlight dashboard, so Open dashboard on the success page doesn’t ask you to sign in again.

When no browser can be reached — the agent is in the cloud, or on a machine with no browser at all — login prints a short code and returns straight away. Your agent can approve that code itself over its existing Greenlight session and then run greenlight login again to pick up the credential. If it can’t (some coding-agent setups have no working Greenlight connection), you can approve the same code yourself: open /cli/approve on your Greenlight dashboard, in a browser already signed in to Greenlight (usually your work profile), and enter it within 10 minutes. That page asks the one question that actually catches a phishing attempt: only enter a code you or your agent created, because nobody at your organization will ever send you one to type there. Anyone in your organization can approve a code this way, including before you’ve built anything.

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.

If you want the detail — what each command does, what the approval page is asking, what an exit code in an agent transcript means — it’s all on the greenlight CLI reference.

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. You can also end that one sign-in by itself, without anyone touching your account: Settings → Plugin sign-ins lists every sign-in acting as you, and ending one stops it immediately — the CLI asks to sign in again the next time your agent uses it. It’s the only standing credential on the machine.

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 .env file — 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

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

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

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 same raw value into the running process. There’s no separate switch for this: granting an injected credential is disclosing it, and IT is told exactly that when it chooses injected delivery at registration and again when it approves the grant. Every delivery is audited under your name, and 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

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 calls inspectAppDb, which runs a read-only query inside Greenlight and returns just the rows. It’s always available for your app’s own database — there’s no toggle to flip — and it runs against the real, vaulted credential on Greenlight’s side, returning results and never the credential itself. 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.

The same applies to an unfamiliar API. Before writing code against a granted proxied integration, the agent can call inspectIntegrationApi to make one request through Greenlight and read the real response shape. Greenlight adds the credential on its side and strips it back out of whatever the upstream returns, so the agent sees the status, headers, and body and never the key. Each call is audited under your name, the same as a database inspection.

A connected database — an Azure SQL or Microsoft Fabric database your organization already runs — works the same way. The agent calls inspectIntegrationDb to run a query such as a list of tables and columns, and Greenlight runs it on its side with the granted identity and returns the rows. Greenlight rolls back what an ordinary query changes, so exploring doesn’t alter the data by accident, and each query is audited under your name. The database role IT granted still decides what the identity can change.

Blob storage — the same proxy as production

If your app stores files, the agent reaches them through Greenlight’s storage proxy — the same path the deployed app uses — via a small module copied into the app. There is no separate storage credential on the machine.

To see what’s stored in the deployed app, the agent calls inspectAppBlob. It lists files under a folder, or looks up one file, and returns names, sizes, types, and dates. It never returns what’s inside a file: those are your users’ uploads, and the agent doesn’t need their contents to build the app. Each call is audited under your name.

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 requestCredentialAccess naming 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 --app flag — 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.

Some credentials are limited to members of certain groups. If you aren’t in one, the request waits for IT instead of auto-approving, and if you leave the group after being granted, greenlight run reports that credential as denied and delivers nothing for it.

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

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 passthrough integrations (where the upstream sees you, not an app) are live as you, in your own account, with real effects: a local run that sends mail sends it from your mailbox. The first time, greenlight run prints a link to connect your account and starts anyway; open it in any browser, and the next call works without a restart. Inspection by the agent runs as you too. Until you connect, the app shows its Connect button, so a local run is also where you see it.

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 — a question for IT, not something to change in the app. The agent may also choose sample data for a user passthrough source when it doesn’t want to act in your real account while it builds.

Your appThe statuses your app moves through, and the Knowledge that makes the agent smarter over time.

Data brokeringThe platform's view of how apps reach data without holding credentials.

Getting help from ITWhen local access or an integration needs IT to step in.