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). 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, its events are kept for 7 days at most and audit streams 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 environmentCopy Anchor Link

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.

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.

--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).

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 dashboardCopy Anchor Link

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 agentsCopy Anchor Link

AI agents can use your development environment over 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:

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

The connector opens a temporary Cloudflare quick tunnel, 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 cloudflaredCopy Anchor Link

--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 tunnelsCopy Anchor Link

• 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 itCopy Anchor Link

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.

TroubleshootingCopy Anchor Link

• 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.