# Permissions & privacy

V3Code Terminal does not silently approve every tool. Risky actions stop and ask you first, and the product is local-first by default.

## The approval prompt

When a guarded action needs approval, you see **Permission required**, the exact target or command, and three choices:

### Allow once

Approves just this one request.

### Allow always

Approves the displayed permission or pattern until V3Code restarts.

### Reject

Stops the action. A child agent can also be given written feedback explaining the rejection.

Prompts can protect edits, reads, file listing, glob and grep searches, shell commands, subagent tasks, web fetches, web searches, access to directories outside the project, language servers and skills, and continuation after repeated failures. Unknown plugin tools can request permission by their own tool name.

> Note:
>
> The `--auto` flag and the palette action **Enable auto-approve permissions** approve anything not explicitly denied. The CLI's own help text calls this **dangerous** — keep it out of defaults and unattended runs.

## Configure permission rules

Permission actions are `ask`, `allow`, and `deny`. A rule can cover a whole tool or just matching patterns.

Project configuration lives in `v3code.json`, `v3code.jsonc`, or under `.v3code/`. User configuration lives under `~/.config/v3code/` on macOS and Linux.

```jsonc
{
  "permission": {
    "edit": "ask",
    "external_directory": "ask",
    "webfetch": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
    },
  },
}
```

**When several patterns match, the last one wins.** So keep the broad fallback first and your specific exceptions after it, exactly as above.

## What touches the network

Run `/privacy` to inspect the policy actually in effect.

Without an opt-in, V3Code Terminal does **not**:

- send product analytics or OTLP telemetry;
- check for updates in the background;
- refresh the model catalog hourly;
- download remote syntax parsers or language servers;
- install plugin dependencies in the background;
- clone or refresh configured remote repository references;
- automatically share sessions.

The built-in model catalog still works from the packaged snapshot or local cache, and anything previously cached stays usable.

Local-first startup also skips the inherited OpenCode account-config refresh, even if an old OpenCode credential is still stored. The upstream account-console and GitHub-bot commands aren't exposed by the V3Code CLI.

### What still uses the network

Traffic that directly serves something you asked for:

- your chosen model provider receives the request context;
- configured MCP servers receive their protocol calls;
- web tools reach the sites you requested;
- an explicit provider login, plugin install, catalog refresh, or confirmed `/share` reaches its named service.

### Opt-in environment variables

| Variable                            | Effect                                         |
| ----------------------------------- | ---------------------------------------------- |
| `V3CODE_ALLOW_BACKGROUND_NETWORK=1` | Allows background dependency traffic.          |
| `V3CODE_ALLOW_TELEMETRY=1`          | Enables telemetry (separately off by default). |
| `V3CODE_ALLOW_AUTO_SHARE=1`         | Enables automatic session sharing.             |
| `V3CODE_ALLOW_REMOTE_PARSERS=1`     | Allows remote syntax parsers only.             |

Each lane is separate on purpose — enabling background network traffic does not turn on telemetry or sharing.

## Troubleshooting

### Provider setup returns on every launch

Setup completes only when a currently available model is selected. Finish **Choose a provider** and **Choose a model**. Run `/connect` to retry authentication, `/models` to pick a usable model, or `v3code providers list` outside the interface. A removed model or missing credential deliberately makes setup return.

### The editor row says `standalone`

Open V3Code Editor as the same local user and run `/bridge` again. The discovery file is `~/.v3code/endpoint.json` — don't hand-edit it. Local memory and index features keep working regardless.

### `/bridge` says the index isn't built

The structural index is lazy and builds on first use. Ask the agent to run `bridge reindex` after a large refactor. Semantic search is separate and only covers locations you approved in the Index tab. If Beast says `not installed`, symbol search still works; only deep trace needs the sidecar.

### A language server or highlighter didn't download

Local-first mode blocks those downloads. Install what you need locally, or set `V3CODE_ALLOW_BACKGROUND_NETWORK=1` deliberately. Run `/privacy` after restarting to confirm.

### Configuration isn't taking effect

```bash
v3code debug config
v3code debug paths
```

V3Code reads the `V3CODE_*` environment prefix first and accepts legacy `OPENCODE_*` aliases for compatibility.

### Startup or runtime failure

```bash
v3code --pure --print-logs --log-level DEBUG
```

`v3code debug startup` prints startup timing and `v3code debug paths` shows the log directory. Remove secrets before sharing logs.

## Related

[Privacy](/account/privacy) covers the editor's policy, and [Permissions](/editor/permissions) covers its approval model.