Remote City Configuration

Save the CLI City's public address and browser origins, then issue a scoped connection code.

city remote manages the CLI City's saved HTTP publishing configuration and issues independent connection credentials. A public URL must already be reachable through your network or reverse proxy. These commands do not create a tunnel or start, stop, or restart City.

Save the address and browser origins

city remote configure --public-url https://city.example.com --allowed-origins https://remote.downcity.ai
city remote show

public_url is the HTTP/HTTPS base URL clients use, including any reverse-proxy path prefix. It is separate from the daemon's listen host and port. Credentials, query strings, fragments, and wildcard listen hosts such as 0.0.0.0 are rejected.

allowed_origins contains exact browser HTTP/HTTPS origins, separated by commas. Each includes its scheme, hostname, and optional port, without a path. Wildcards and embedded credentials are rejected. The list is replaced when supplied; omitted fields keep their saved values. An empty list allows no additional cross-origin browser access. Origins do not grant Agent access; Bearer authorization still applies.

city remote configure --allowed-origins https://remote.downcity.ai,http://localhost:5173
city remote configure --clear-allowed-origins
city remote configure --clear-public-url

With no configuration flags, configure prompts for both fields in a real terminal. Blank answers clear the corresponding setting. Cancelling or entering an invalid field saves nothing. All three subcommands accept --root <path> and --json.

Saved settings live in the selected City root's configuration database. show reports saved values, not the currently running HTTP configuration. configure --json returns restart_required: true. Apply changes by explicitly stopping and starting the CLI City with your required listen parameters:

city off
city on --host 127.0.0.1 --port 5314

Choose the listen host and port for your own proxy setup. Saving a public URL does not change the listen address. CLI settings apply when the CLI City runtime starts.

Issue a connection code

city remote code
city remote code --name browser-review --agents reviewer --never-expires --json
city remote code --public-url https://city.example.com --name browser-review --all-agents --expires-at 2030-01-01T00:00:00Z

Missing name, Agent scope, or expiry options are collected interactively and confirmed before issuance. For scripts, provide --name, either --agents or --all-agents, and either --expires-at or --never-expires. Agent IDs must exist. Expiry follows the City Token rules; an explicit date must be in the future.

The command uses the saved public URL unless --public-url supplies an address for this code only. This override is not saved. Without either address it fails before issuing a Token; it does not guess a listen host or port. URL validation precedes credential issuance.

Each invocation creates an independent City Token through the trusted local management channel, using the same authorization and expiry settings as city token create. Offline issuance uses the existing local resource path and requires a City root already prepared for offline resource access; roots that need coordination or database recovery must be prepared by explicitly starting a supported host. The command never starts one automatically. No previous Token plaintext can be recovered or reused. No Token input flag is provided.

The human-readable output contains the citycode: connection code and the Token ID for revocation. JSON output contains code, url, and the Token summary fields, without a separate raw token field. The code packages the address and credential using the City SDK format. It is not encrypted: treat it as a credential and copy it directly to the connecting application.

Manage its authorization and expiry with city token update <token_id>; revoke it with city token delete <token_id>. Revocation invalidates credentials inside previously copied codes. Token management must target the same City data root, using that root's normal CLI environment configuration.