HTTP and RPC

Expose an Agent through the City host transport adapters.

City owns one HTTP transport and one RPC transport. Both route by agent_id to the same Agent collection and by workspace_id to a Workspace owned by City.

await city.listen({
  http: { host: "127.0.0.1", port: 5314 },
  rpc: { host: "127.0.0.1", port: 15314 },
});

await city.close(); // transports only; the creating host still disposes Agents

For separate lifecycle control, City can start either transport directly:

const http = await city.http({ host: "127.0.0.1", port: 5314 });
const rpc = await city.rpc({ host: "127.0.0.1", port: 15314 });

HTTP uses http://host:port/agents/<agent_id>/workspaces/<workspace_id> and RPC uses rpc://host:port/<agent_id>/<workspace_id>. External services belong to City.

Listener and client address

The listener receives requests; runtime.http.public_url is the address clients use. They are independent. For a user-managed Cloudflare Tunnel, keep City listening on loopback and point your HTTPS domain at that listener:

import { City } from "@downcity/city";

const city = new City({
  runtime: {
    http: {
      public_url: "https://city.example.com",
      allowed_origins: ["https://remote.downcity.ai"],
      authorize_agent: ({ agent, request }) =>
        authorize_city_token(request.headers.get("Authorization"), agent.id),
    },
  },
});

const http = await city.http({ host: "127.0.0.1", port: 5314 });
const listen_address = http.binding()?.url; // http://127.0.0.1:5314
const client_address = http.client_url();  // https://city.example.com
// issued_token is an independent credential already issued by your host.
const connection_code = http.connection_code(issued_token);

authorize_city_token represents your host's actual validation function. Configuring public_url, or starting a listener on a non-loopback address, requires an explicit authorize_agent callback. A callback must validate the credential and Agent scope for each request.

client_url() returns the normalized explicit address, or the actual listener address when none is configured. Before listening it returns null unless public_url is set. Wildcard bindings such as 0.0.0.0 and :: are not client destinations: configure an explicit address before generating connection codes. connection_code(token) only packages an address and an existing credential; it does not issue access or verify reachability.

The advertised address is never inferred from Host, Forwarded or X-Forwarded-*. Registering it does not create DNS, a certificate, a Tunnel, or proof that the endpoint reaches this City. HTTP and HTTPS addresses are valid SDK targets; the browser client applies its own protocol and local-network rules.

A reverse-proxy path prefix is allowed, for example https://example.com/my-city. Your proxy must strip /my-city before forwarding to the City root. Configuring public_url does not remount routes.

HTTP exposure and Tunnel

City's default HTTP routes provide Agent discovery and authenticated Agent/Workspace SDK access when an authorization callback is configured. There is no default /internal/status route or HTTP token-management API. Token creation and revocation remain with the trusted host. The RPC listener is separate and should not be forwarded by an HTTP Tunnel.

city_router and create_agent_extension explicitly add host routes; audit and authorize those routes before exposing the listener. An Agent credential grants the SDK capabilities available to that Agent, not a chat-only permission. CORS is not a substitute for authorization, and clients without an Origin header must still be authenticated.

Configure and run your own Cloudflare Named Tunnel, with a fixed HTTPS hostname forwarding to the loopback listener. Preserve Origin, Authorization, methods and bodies; forward OPTIONS and NDJSON event streams without buffering or caching. Prefer forwarding only the discovery paths /api/sdk/agents, /api/sdk/agents/:agent_id and the required /agents/... SDK routes. Do not log connection codes, authorization headers or message bodies. Extra Cloudflare Access login is a separate integration and must not be assumed to work with cross-origin Fetch automatically.

Remote and Chrome Extension both connect through RemoteCity from @downcity/city/browser; city.agents.get() returns a client for the existing server Agent. Tunnel does not create an Agent or a second City runtime.

Browser connections

For Desktop, enable Settings → City Remote, then select Create connection code. Enter a recipient note and a City address reachable by the recipient, select Agent permissions and expiry, and copy the complete code from its one-time display. Each creation issues an independent token; closing the dialog clears the code. Existing authorizations can be edited or revoked, but their plaintext cannot be recovered.

Paste the code into Remote's single connection-code field. Remote decodes it locally and displays the City address; confirm it before clicking Connect. The browser connects directly to City without forwarding through a Downcity backend. Remote does not take codes from the page URL or save codes or credentials. Only a non-sensitive City address may be remembered.

For a custom host, configure exact browser origins on the City HTTP runtime before starting its listener:

import { City } from "@downcity/city";

const city = new City({
  runtime: {
    http: {
      allowed_origins: [
        "https://remote.downcity.ai",
        "http://127.0.0.1:5173",
      ],
      authorize_agent: ({ agent, request }) =>
        authorize_city_token(request.headers.get("Authorization"), agent.id),
    },
  },
});

await city.http({ host: "127.0.0.1", port: 5314 });

authorize_city_token represents your host's credential validation. Origin permission does not grant access to an Agent; discovery and Agent requests still use the host's authorization callback.

allowed_origins accepts HTTP/HTTPS origins with an exact scheme, hostname and port. Wildcards, credentials, paths, queries and fragments are rejected. Omitting the field does not install CORS; an empty list rejects cross-origin browser requests. Requests without an Origin header continue through the regular authorization path.

Allowed origins receive CORS headers on JSON and streaming responses. Preflight requests return 204 without Agent authorization, permitting GET, POST, OPTIONS, Authorization and Content-Type. Disallowed origins, preflight methods and request headers return 403. Cross-origin cookies are not enabled.

CORS does not provide HTTPS or network reachability. The HTTPS Remote site permits HTTP only for the exact loopback hosts 127.0.0.1, localhost and [::1]; the browser may require local network permission and can still block access according to its policy. Other targets, including LAN IP addresses, require a reachable HTTPS endpoint with streaming responses forwarded without buffering. Chrome Extension uses extension network permissions rather than the webpage's endpoint policy. Desktop's City Remote already permits https://remote.downcity.ai, http://127.0.0.1:5173 and http://localhost:5173. The default Desktop address http://127.0.0.1:5314 is suitable for a local Remote on the same computer. Other recipients need an address reachable from their browser; DNS and an origin allowlist do not create a tunnel.

Connection-code API

@downcity/city/browser exports encode_city_connection({ url, token }), decode_city_connection(code) and the CityConnection type. CityConnection.url is the HTTP/HTTPS City address reachable by the recipient; CityConnection.token is the authorization credential. The helpers encode and decode locally without sending or persisting data.

import {
  encode_city_connection,
  decode_city_connection,
  type CityConnection,
} from "@downcity/city/browser";

// Fictional documentation values; never log or publish real credentials or codes.
const connection: CityConnection = {
  // HTTP/HTTPS City address that the recipient's browser can reach.
  url: "https://city.example.com",
  // Fictional token placeholder; use an independently issued credential in your app.
  token: "EXAMPLE_ONLY_NOT_A_REAL_TOKEN",
};
const connection_code = encode_city_connection(connection);
const decoded_connection = decode_city_connection(connection_code);
// Display decoded_connection.url for confirmation before connecting.

The wire format is citycode:<base64url UTF-8 JSON {url,token}>, with an unpadded base64url payload. Validation rejects an unsupported prefix, malformed base64url, invalid UTF-8 or JSON, missing or non-string fields, and invalid addresses or credentials. Addresses must use HTTP/HTTPS without embedded credentials, query strings, fragments or wildcard hostnames. Tokens must be nonempty, at most 8,192 characters after trimming, and contain no whitespace. Codes are limited to 32,768 characters. Invalid input throws an error; successful decoding only validates the format, not City reachability, token validity or Agent permissions.

Encoding is not encryption. Anyone holding the code can use its authorized Agents until expiry or revocation. Send it privately and revoke exposed authorizations. A recipient note does not bind access to an identity or prevent forwarding.