Ambit MCP

What This Is

You are operating through the Ambit MCP server. This server gives you access to Fly.io — a cloud platform for running apps — but wraps every operation in a safety layer designed for AI agents. The key constraint: you can only ever deploy things onto a private network. There is no option to make an app public, allocate a public IP, or expose anything to the internet. This is intentional. It means you can deploy freely without risk of accidentally making a database or internal tool reachable by strangers.

Apps you deploy land on a private Ambit network (e.g. lab, staging, personal). They get addresses like http://my-app.lab that work for any device enrolled in the user’s Tailscale network, and are unreachable from anywhere else. Tailscale is a VPN that links the user’s devices into a sealed private network — devices enrolled in it can connect to each other; devices that aren’t cannot.

Installation

If ambit-mcp is not already installed, run it directly via npx:

npx @cardelli/mcp

Operating Modes

• Safe Mode (default): Private networking is enforced on every operation. Router management tools are available. Public IP allocation tools do not exist.
• Unsafe Mode: Full flyctl surface with no restrictions. No router tools.

You are most likely in safe mode. If a tool you expect is missing, check which mode is active by examining your available tool list.

Standard Deployment Workflow

To get a new app running on the private network, call tools in this order:

1. fly_app_create — Create the app. In safe mode the network is set automatically.
2. fly_secrets_set with stage: true — Set any API keys, database URLs, or tokens before deploying. Using stage: true queues the secrets without triggering a redeploy on an app that has no code yet.
3. fly_deploy — Deploy the image, dockerfile, or template. Safe mode auto-injects --no-public-ips --flycast and audits the result immediately.
4. fly_ip_allocate_flycast — Allocate a private Flycast IPv6 address on the correct network name. Without this step the app is running but nothing can reach it — the router has no address to forward traffic to.
5. fly_app_status and fly_logs — Verify machines are running and check for startup errors.

After this, the app is reachable from the user’s tailnet as http://<app-name>.<network>.

Template Deployment

fly_deploy supports a template field for deploying from GitHub-hosted templates. Pass a reference in the format owner/repo/path[@ref]:

• ToxicPine/ambit-templates/chromatic — headless Chrome with CDP on port 9222
• ToxicPine/ambit-templates/wetty — web terminal with persistent storage
• ToxicPine/ambit-templates/opencode — Nix-based development environment
• ToxicPine/ambit-openclaw — self-hosted personal AI assistant reachable from WhatsApp, Telegram, Discord, etc.

The template field is mutually exclusive with image and dockerfile. When provided, the MCP server fetches the template from GitHub, extracts the target subdirectory, and deploys it. The template must contain a fly.toml (and typically a Dockerfile).

Example workflow for deploying a browser via template:

1. fly_app_create with name my-browser
2. fly_deploy with template: "ToxicPine/ambit-templates/chromatic"
3. fly_ip_allocate_flycast with the network name
4. Browser is now reachable at my-browser.<network>:9222 via CDP

Key Rules

1. Secrets go in fly_secrets_set, not env in fly_deploy. Variables passed as env in a deploy are visible in the app config. Secrets are encrypted at rest and are the right place for anything sensitive.
2. Always allocate a Flycast IP after deploying. An app without a Flycast IP is running but unreachable. fly_ip_allocate_flycast must be called with the correct network name after every first deploy.
3. Use stage: true when setting secrets before the first deploy. Without it, each fly_secrets_set call triggers a redeploy attempt on an app with no code yet.
4. Check fly_auth_status first when debugging. Most failures trace back to expired or missing authentication.
5. The confirm field on fly_volumes_destroy must exactly match volume_id. Do not generate a different value or skip it.
6. Router tools only exist in safe mode. If router_* tools are absent from your tool list, the server is in unsafe mode.
7. fly_deploy auditing is automatic in safe mode. If public IPs are found after a deploy they are released automatically, but the deploy is flagged as an error — report this to the user.

Troubleshooting