# VS Code Extension

> Set up the RunEnv VS Code extension for local development and debugging.

Canonical HTML: /en/docs/client-interfaces/vscode
Canonical Markdown: /agent-docs/client-interfaces/vscode.md
Audience: developer
Agent safety: context-only

---

The RunEnv VS Code extension helps developers inspect project configuration and prepare a safe local debugging workflow. It is a convenience layer over the RunEnv CLI and API; it never connects directly to the database.

## Install and sign in

1. Install the **RunEnv** extension from the VS Code Marketplace.
2. Open the RunEnv activity view and choose **Sign in**.
3. Complete browser authentication, then return to VS Code.
4. Open the repository that contains your `.runenv.json` link file.

For a self-hosted deployment, configure the extension with the same HTTPS server URL used by the CLI and Dashboard.

## Link a workspace

Use the command palette to run **RunEnv: Link Project**, or link from the terminal:

```bash
runenv link --project my-api --env development
```

The link file stores project and environment context only. It must not contain secret values.

## Debug with a controlled `.env` file

Some launch configurations require an environment file. Generate one only when that workflow requires it:

```bash
runenv dotenv --setup --project my-api --env development
```

Review the generated VS Code task and launch configuration before using it. Remove the file when it is no longer needed:

```bash
runenv dotenv --clean
```

> **Prefer runtime injection**
>
> For normal development, prefer `runenv run -- <command>` so values are injected into the process without creating a local environment file.

## Daily workflow

Use the extension to confirm your linked project and environment, then run your app through the CLI:

```bash
runenv run -- npm run dev
```

If the extension cannot load a project, first run `runenv status` and confirm the active organization, project link, and server URL. Do not paste a token into a workspace setting or source file.

## Security and resilience

* Secret values are not placed in `.vscode/settings.json` or `.runenv.json`.
* Access is evaluated by the RunEnv API using the signed-in identity and project permissions.
* Keep VS Code, the extension, and the RunEnv CLI updated.
* If sign-in or the configured server changes, sign out and authenticate again rather than copying credentials between machines.