# Development environments

Give each member an environment of their own, served by the connector on their computer against their local database, and share it with AI agents through a temporary tunnel.

Source: https://docs.getaviato.com/integrations/development-environments

A development environment is an environment of a project that belongs to one member. The connector runs on that member's computer, next to their local database and plugin, and the dashboard shows the back-office of what they are building: the schema of their migrations, the actions of their plugin code, their test records. Nobody shares a connector token, and nobody else's work shows up in it.

Development environments need connector **0.5.0** or later, and Laravel SDK **0.8.0** for `php artisan aviato:serve`. Any member of the workspace can open one, with no role or plan required. It differs from the project's other environments in five ways:

* **It is yours.** Only you see it in the environment switcher and open its back-office; other members, managers included, do not. Approving it signs nothing else in: the connector receives this environment's credential, not your session.
* **It is outside the plan's limits.** It does not count against the environments per project (see [Plans and limits](/administration/plans-and-limits)). Each member has at most one per project.
* **It removes itself.** Aviato removes it when its connector has not reported for 30 days, or when you leave the workspace.
* **Its audit trail is short.** As for [preview environments](/integrations/preview-environments), its events are kept for 7 days at most and [audit streams](/administration/audit) leave them out. Audit exports still include them.
* **It runs on your computer, even for a hosted project.** Aviato never starts a hosted connector for it.

## Start your development environment [#start-your-development-environment]

Run the connector's `dev` command with the project's id. The dashboard shows the command, with the id filled in, under the project's **Settings → Environments → Develop locally**.

```bash
aviato-connector dev --project 4f7c6a52-3b7d-4c39-9d1f-3f0f6a1f2b10
```

With Laravel, run `php artisan aviato:serve --dev --project=<project id>` instead.

The first time, the connector opens the dashboard's **Develop locally** page and prints a code:

```
  Approve this computer in your browser: https://app.getaviato.com/device?user_code=WDJBMJHT
  Check that the page shows the code WDJB-MJHT.
```

Sign in if needed, check that the page shows the same code and the right project, then approve. The code expires after 10 minutes. Aviato creates your environment, named `dev-` and the start of your email (for example `dev-ada-lovelace`), and the connector starts with its credential.

The credential is stored in `~/.config/aviato/development.json` (`$XDG_CONFIG_HOME/aviato` when set, `%APPDATA%\aviato` on Windows), readable only by you and outside your repository, so it is never committed. Later runs reuse it and start right away.

| Option           | Effect                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--project <id>` | The project whose development environment to run.                                                                    |
| `AVIATO_PROJECT` | Replaces `--project`, for example in `aviato.env` or Laravel's `.env`. Ignored when `AVIATO_CONNECTOR_TOKEN` is set. |
| `--login`        | Approves this computer again instead of reusing the stored credential.                                               |
| `--no-open`      | Prints the approval link without opening a browser, for example over SSH.                                            |
| `--tunnel`       | Shares the connector through a temporary public address; see [Connect AI agents](#connect-ai-agents).                |

`--project` always takes precedence; without it, a connector token in `AVIATO_CONNECTOR_TOKEN` takes precedence over `AVIATO_PROJECT`. The other options of `dev`, such as `--types`, work as usual (see [Typed plugins and local development](/integrations/plugin-development)).

Approving again, from this computer or another one, replaces the environment's credential: the connector that used the previous one stops with an error, forgets it, and asks you to run the command again. Run one development connector per project at a time.

## Use it in the dashboard [#use-it-in-the-dashboard]

The command prints your environment's link. In the dashboard's environment switcher, it appears under **Local development**; the project's **Settings → Environments** lists it with a **Local** badge.

The connector advertises `http://localhost:8080` (or the port in `PORT`), and the dashboard reaches it from your browser on the same computer. Your browser may ask whether the dashboard can access devices on your local network; allow it. If the connector is not running, the dashboard says so instead of showing records.

## Connect AI agents [#connect-ai-agents]

AI agents can use your development environment over [MCP](/integrations/mcp), with your access only. MCP clients, and Aviato when it checks that the connector owns its address, must reach the connector over HTTPS from outside your computer. Add `--tunnel`:

```bash
aviato-connector dev --project <project id> --tunnel
```

The connector opens a temporary [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/), waits until its address answers, advertises it instead of `localhost`, and prints the MCP URL to give your client:

```
  Tunnel open at https://calm-river-1234.trycloudflare.com until you stop the connector. MCP clients connect to https://calm-river-1234.trycloudflare.com/mcp.
```

The dashboard reaches the connector through the tunnel too. The tunnel closes when you stop the connector. With Laravel, add `--tunnel` to `php artisan aviato:serve --dev`.

A public address does not make your data public: the connector serves records, actions and MCP only to requests carrying a token Aviato issued to you for this environment. Its health check (`/v1/health`) answers anyone, as on any connector.

### Install cloudflared [#install-cloudflared]

`--tunnel` runs Cloudflare's `cloudflared`. No Cloudflare account is needed. The connector uses, in order:

1. `cloudflared` on your `PATH`, installed for example with `brew install cloudflared`.
2. The copy it installed earlier in `~/.local/share/aviato/bin` (`$XDG_DATA_HOME/aviato/bin` when set, `%LOCALAPPDATA%\aviato\bin` on Windows).
3. Otherwise it asks whether to download Cloudflare's latest release for your system into that directory, and installs it only if it matches the SHA-256 checksum GitHub lists for that release. No administrator rights are needed.

Without a terminal to ask, as under `php artisan aviato:serve`, passing `--tunnel` counts as agreement. Remove the directory to uninstall it.

### Limits of quick tunnels [#limits-of-quick-tunnels]

* **The address changes on every run.** Give your MCP client the new URL each time you restart the connector.
* **They are for development.** Quick tunnels have no uptime guarantee and answer `429` beyond 200 requests in flight.
* **It can take a minute to resolve.** When the address is not answering after 30 seconds, the connector starts anyway and says so; it usually works shortly after.

For a fixed address, run your own tunnel (a named Cloudflare Tunnel, ngrok, Tailscale Funnel) to the connector's port and set `AVIATO_PUBLIC_URL` to its HTTPS address instead of passing `--tunnel`.

## Remove it [#remove-it]

Remove your development environment from the project's **Settings → Environments**. Its credential stops working at once and a running connector stops; run `dev` again to approve this computer and create a new one. Workspace owners and project managers cannot see or remove other members' development environments; Aviato removes them after 30 days without a report, or when the member leaves.

## Troubleshooting [#troubleshooting]

* **The approval page refuses the code.** Check that it matches the terminal and has not expired; run the command again for a new one. Approval needs a verified email and membership of the project's workspace.
* **"Your development environment was removed or its credential replaced."** The environment was removed, or approved again elsewhere. Run the command again to approve this computer.
* **The dashboard cannot reach the connector.** Check that `aviato-connector dev` is running on this computer and that your browser may access the local network. With `--tunnel`, check the terminal for a message that the tunnel closed, and restart the command.
* **"No tunnel without cloudflared."** You declined the download. Install `cloudflared` yourself, or set `AVIATO_PUBLIC_URL` to another tunnel's address.