ambit-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ambit CLI

What Ambit Is

什么是Ambit

Ambit deploys apps to the cloud in a way that makes them completely unreachable from the public internet. Only devices enrolled in the user's private Tailscale network can connect to them. From the outside world's perspective, the app does not exist — there is no IP address to find, no port to scan.

This matters because putting a database, dashboard, or internal tool on the normal internet forces you to build login pages, configure firewalls, and harden the app against strangers. Ambit skips all of that. Access control is handled at the network level: if a device is on the Tailscale network, it can reach the app; if it isn't, the connection is refused before the app ever sees it.

Each private network you create is called an ambit. Every app deployed to it gets a human-readable address under that network's name — so

http://my-app.lab

means the

my-app

application on the

lab

ambit. These addresses work automatically for any device enrolled in the user's Tailscale account.

Ambit可将应用部署到云端，且使其完全无法从公共互联网访问。只有加入用户私有Tailscale网络的设备才能连接这些应用。从外部网络的视角来看，这些应用仿佛不存在——没有可查找的IP地址，也没有可扫描的端口。

这一点至关重要，因为将数据库、仪表板或内部工具部署到常规互联网时，你必须构建登录页面、配置防火墙，并强化应用以抵御外部访问。而Ambit可跳过所有这些步骤。访问控制在网络层面处理：如果设备处于Tailscale网络中，就能访问应用；如果不在，连接会在应用感知到之前就被拒绝。

你创建的每个私有网络都被称为一个ambit。部署到该网络的每个应用都会获得一个基于该网络名称的人类可读地址——例如

http://my-app.lab

代表

lab

ambit上的

my-app

应用。这些地址对所有加入用户Tailscale账户的设备自动生效。

Installation

安装

ambit

is not already installed, run it directly via Nix:

bash

npx @cardelli/ambit

如果尚未安装Ambit，可通过Nix直接运行：

bash

npx @cardelli/ambit

How It Works

工作原理

mermaid

graph LR
    A[Your Device<br/>on Tailscale] -->|Tailscale tunnel| B[Ambit Router<br/>Fly.io VM]
    B -->|Flycast / private IPv6| C[Your App<br/>no public IP]

Ambit creates a router on Fly.io that joins the user's Tailscale network and advertises the private IPv6 subnet for that ambit. It also sets up split DNS so that

*.<network>

queries resolve to the right app. Apps deployed with

ambit deploy

get a private Flycast address on the network and never receive a public IP.

mermaid

graph LR
    A[你的设备<br/>已加入Tailscale] -->|Tailscale隧道| B[Ambit路由器<br/>Fly.io虚拟机]
    B -->|Flycast / 私有IPv6| C[你的应用<br/>无公网IP]

Ambit会在Fly.io上创建一个路由器，该路由器会加入用户的Tailscale网络，并为该ambit广播私有IPv6子网。它还会配置拆分DNS，以便

*.<network>

查询能解析到对应的应用。使用

ambit deploy

部署的应用会获得该网络上的私有Flycast地址，且永远不会分配公网IP。

Prerequisites

前提条件

```
flyctl
```
installed and authenticated (
```
fly auth login
```
)
Tailscale installed and connected (
```
tailscale up
```
)
Accept-routes enabled (
```
sudo tailscale set --accept-routes
```
)
A Tailscale API access token (
```
tskey-api-...
```
) — create one at https://login.tailscale.com/admin/settings/keys

已安装并认证
```
flyctl
```
（执行
```
fly auth login
```
）
已安装并连接Tailscale（执行
```
tailscale up
```
）
已启用接受路由（执行
```
sudo tailscale set --accept-routes
```
）
拥有Tailscale API访问令牌（格式为
```
tskey-api-...
```
）——可在https://login.tailscale.com/admin/settings/keys创建

Commands

命令

ambit create <network>

ambit create <network>

Creates a new private network. This is the first command to run when setting up a new ambit. It deploys a router on Fly.io, connects it to the user's Tailscale network, and configures split DNS so apps on the network are reachable by name.

bash

ambit create lab
ambit create lab --org my-org --region sea
ambit create lab --self-approve

Flags:

```
--org <org>
```
— Fly.io organization slug
```
--region <region>
```
— Fly.io region (default:
```
iad
```
)
```
--api-key <key>
```
— Tailscale API access token (prompted interactively if omitted)
```
--tag <tag>
```
— Tailscale ACL tag for the router (default:
```
tag:ambit-<network>
```
)
```
--self-approve
```
— Approve subnet routes via Tailscale API instead of requiring autoApprovers in the ACL policy
```
-y, --yes
```
— Skip confirmation prompts
```
--json
```
— Output as JSON

What it does:

Validates Fly.io auth and the Tailscale API key
Checks that the tag (default
```
tag:ambit-<network>
```
, or custom via
```
--tag
```
) exists in Tailscale ACL tagOwners
Checks autoApprovers config (unless
```
--self-approve
```
)
Creates a Fly.io app on the custom network

Sets secrets:

TAILSCALE_API_TOKEN

NETWORK_NAME

TAILSCALE_TAGS

Deploys the router container
Waits for the device to join the tailnet
Configures split DNS (
```
*.<network>
```
→ router)
Enables accept-routes locally if possible

Before running, the user must add the router's tag in their Tailscale ACL settings at https://login.tailscale.com/admin/acls/visual/tags. The tag defaults to

tag:ambit-<network>

but can be overridden with

--tag

And optionally (or use

--self-approve

to skip this):

json

"autoApprovers": { "routes": { "fdaa:X:XXXX::/48": ["tag:ambit-<network>"] } }

创建一个新的私有网络。这是设置新ambit时要运行的第一个命令。它会在Fly.io上部署一个路由器，将其连接到用户的Tailscale网络，并配置拆分DNS，以便网络上的应用可通过名称访问。

bash

ambit create lab
ambit create lab --org my-org --region sea
ambit create lab --self-approve

参数：

```
--org <org>
```
— Fly.io组织标识
```
--region <region>
```
— Fly.io区域（默认值：
```
iad
```
）
```
--api-key <key>
```
— Tailscale API访问令牌（如果省略，会交互式提示输入）
```
--tag <tag>
```
— 路由器的Tailscale ACL标签（默认值：
```
tag:ambit-<network>
```
）
```
--self-approve
```
— 通过Tailscale API批准子网路由，无需在ACL策略中配置autoApprovers
```
-y, --yes
```
— 跳过确认提示
```
--json
```
— 以JSON格式输出

执行流程：

验证Fly.io认证和Tailscale API密钥
检查标签（默认
```
tag:ambit-<network>
```
，可通过
```
--tag
```
自定义）是否存在于Tailscale ACL的tagOwners中
检查autoApprovers配置（使用
```
--self-approve
```
时跳过）
在自定义网络上创建Fly.io应用

设置密钥：

TAILSCALE_API_TOKEN

、

NETWORK_NAME

、

TAILSCALE_TAGS

部署路由器容器
等待设备加入tailnet
配置拆分DNS（
```
*.<network>
```
→ 路由器）
尽可能在本地启用接受路由

运行前准备：用户必须在Tailscale ACL设置页面（https://login.tailscale.com/admin/acls/visual/tags）中添加路由器的标签。标签默认为`tag:ambit-<network>

，可通过

--tag`覆盖。

或者（或使用

--self-approve

跳过此步骤）：

json

"autoApprovers": { "routes": { "fdaa:X:XXXX::/48": ["tag:ambit-<network>"] } }

ambit deploy <app> --network <name>

ambit deploy <app> --network <name>

Deploys an app onto a private network. This is the safe alternative to

fly deploy

: it always passes

--no-public-ips

and

--flycast

, runs pre-flight checks on the fly.toml for dangerous settings, and audits the result to verify no public IPs were allocated.

bash

ambit deploy my-app --network lab
ambit deploy my-app --network lab --image registry.fly.io/my-app:latest

Flags:

```
--network <name>
```
— Target network (required)
```
--org <org>
```
— Fly.io organization
```
--region <region>
```
— Primary region
```
--image <img>
```
— Docker image to deploy (instead of fly.toml)
```
--config <path>
```
— Explicit path to fly.toml
```
-y, --yes
```
— Skip confirmation
```
--json
```
— Output as JSON

将应用部署到私有网络。这是

fly deploy

的安全替代方案：它始终传递

--no-public-ips

和

--flycast

参数，会对fly.toml中的危险设置进行预检查，并审核结果以确保未分配公网IP。

bash

ambit deploy my-app --network lab
ambit deploy my-app --network lab --image registry.fly.io/my-app:latest

参数：

```
--network <name>
```
— 目标网络（必填）
```
--org <org>
```
— Fly.io组织
```
--region <region>
```
— 主区域
```
--image <img>
```
— 要部署的Docker镜像（替代fly.toml）
```
--config <path>
```
— fly.toml的明确路径
```
-y, --yes
```
— 跳过确认
```
--json
```
— 以JSON格式输出

ambit list

ambit list

Lists all discovered routers across all networks.

bash

ambit list
ambit list --org my-org --json

Shows: network name, app name, region, machine state, private IP, subnet, and Tailscale device status.

列出所有网络中已发现的路由器。

bash

ambit list
ambit list --org my-org --json

显示内容包括：网络名称、应用名称、区域、机器状态、私有IP、子网和Tailscale设备状态。

ambit status

ambit status

Shows detailed router status. Run without

--network

to see all routers, or with

--network

to focus on one.

bash

ambit status
ambit status --network lab

Detailed view includes: machine state, SOCKS5 proxy address, Tailscale IP, online status, advertised routes, and split DNS config.

显示路由器的详细状态。不带

--network

参数运行可查看所有路由器，带该参数则聚焦于指定网络的路由器。

bash

ambit status
ambit status --network lab

详细视图包括：机器状态、SOCKS5代理地址、Tailscale IP、在线状态、广播路由和拆分DNS配置。

ambit destroy --network <name>

ambit destroy --network <name>

Tears down a router and cleans up all associated resources. Apps deployed on the network are NOT deleted — only the router is removed. The user will need to manually remove ACL policy entries for the network tag.

bash

ambit destroy --network lab
ambit destroy --network lab --yes

What it does:

Finds the router app for the network
Clears split DNS configuration
Removes the Tailscale device
Destroys the Fly.io app

拆除路由器并清理所有相关资源。部署在该网络上的应用不会被删除——仅移除路由器。用户需要手动删除ACL策略中与该网络标签相关的条目。

bash

ambit destroy --network lab
ambit destroy --network lab --yes

执行流程：

查找该网络对应的路由器应用
清除拆分DNS配置
移除Tailscale设备
删除Fly.io应用

ambit doctor

ambit doctor

Health check for the local environment and router infrastructure. Run this whenever something seems wrong — it checks the most common failure points and gives remediation hints.

bash

ambit doctor
ambit doctor --network lab

Checks:

Tailscale CLI installed
Tailscale connected (BackendState = Running)
Accept-routes enabled
Router(s) exist and machines are running
Router(s) visible in tailnet

本地环境和路由器基础设施的健康检查。当出现问题时运行该命令——它会检查最常见的故障点并给出修复建议。

bash

ambit doctor
ambit doctor --network lab

检查项：

是否已安装Tailscale CLI
Tailscale是否已连接（BackendState = Running）
是否已启用接受路由
路由器是否存在且机器正在运行
路由器在tailnet中是否可见

Common Workflows

常见工作流

First-Time Setup

首次设置

bash

undefined

bash

undefined

1. Add tag to Tailscale ACL policy in the web UI

1. 在网页UI中为Tailscale ACL策略添加标签

2. Create the router

2. 创建路由器

ambit create lab --self-approve

3. Deploy an app

3. 部署应用

ambit deploy my-app --network lab

4. App is now reachable as http://my-app.lab from any device on the tailnet

4. 现在可从tailnet中的任何设备以http://my-app.lab访问该应用

5. Invite people to your tailnet:

5. 邀请他人加入你的tailnet：

https://login.tailscale.com/admin/users

6. Control their access:

6. 控制他们的访问权限：

https://login.tailscale.com/admin/acls/visual/general-access-rules

undefined

undefined

Debugging Connectivity

连接问题调试

bash

ambit doctor --network lab    # Check all the common failure points
ambit status --network lab    # Detailed router state

bash

ambit doctor --network lab    # 检查所有常见故障点
ambit status --network lab    # 查看路由器详细状态

Tearing Down

拆除环境

bash

ambit destroy --network lab

bash

ambit destroy --network lab

Then remove from Tailscale ACL:

然后从Tailscale ACL中移除相关内容：

tagOwners: tag:ambit-lab

autoApprovers: routes for tag:ambit-lab

autoApprovers: tag:ambit-lab对应的路由

undefined

undefined

Troubleshooting

故障排除

Symptom	Fix
"Tag not configured in tagOwners"	Add `"tag:ambit-<network>": ["autogroup:admin"]` to Tailscale ACL tagOwners.
"autoApprovers not configured"	Either configure autoApprovers in the ACL or re-run with `--self-approve` .
Router deployed but not reachable	Run `ambit doctor` . Check that accept-routes is enabled locally.
"Timeout waiting for device"	Check router logs. Most common cause: expired or invalid Tailscale API key.
Apps not resolving as `<app>.<network>`	Verify split DNS is configured: `ambit status --network <name>` . Check the router is online in the tailnet.
"Flyctl not found"	Install from https://fly.io/docs/flyctl/install/

症状	修复方法
"Tag not configured in tagOwners"	在Tailscale ACL的tagOwners中添加 `"tag:ambit-<network>": ["autogroup:admin"]` 。
"autoApprovers not configured"	要么在ACL中配置autoApprovers，要么使用 `--self-approve` 重新运行命令。
路由器已部署但无法访问	运行 `ambit doctor` 。检查本地是否已启用接受路由。
"Timeout waiting for device"	查看路由器日志。最常见的原因是Tailscale API密钥过期或无效。
应用无法通过 `<app>.<network>` 解析	验证拆分DNS是否已配置：执行 `ambit status --network <name>` 。检查路由器在tailnet中是否在线。
"Flyctl not found"	从https://fly.io/docs/flyctl/install/安装。