Custom gateways in TypeScript

Connect your own service without editing devctrl. Write a gateway in TypeScript, JavaScript or another runtime, run it on an execution host, and register its endpoint with a YAML or JSON host service definition. The normal Services UI, health checks, project grants and fixed-target routes then apply.

A gateway can translate an API, narrow the allowed operations or keep upstream credentials on the host. A plain TCP service can be registered directly without writing a gateway. For a reusable distribution, ship the gateway and definition as an optional provider package.

Where files belong

Installation Host service directory
Local Docker ~/.config/devctl/hosts/localhost/services.d/ on the developer machine
SSH host ~/.config/devctl/hosts/<ssh-alias>/services.d/ in the SSH user's home, on that host
Standalone server /var/lib/devctl/services.d/ on the server
Rootless standalone ${DEVCTL_ROOTLESS_ROOT}/execution/services.d/

For SSH installation, prepare files under the matching alias on the developer machine; install-host copies that alias's services.d contents to the remote user's corresponding directory. Later edits to the local copy are not live file synchronization: update the remote source explicitly, or run host installation again when appropriate.

The host agent discovers *.yaml, *.yml and *.json files in its configured directory. It does not automatically execute .ts files. Put gateway code under services.d/scripts/, with its definition beside that directory:

services.d/
├── custom-api.yaml
└── scripts/
    └── custom-read-gateway.ts

In Docker-backed host installations the directory is mounted read-only at /etc/devctl/services.d/ inside the host agent. DEVCTL_HOSTS_CONFIG_DIR and DEVCTL_LOCAL_SERVICES_DIR override local configuration sources; DEVCTL_HOST_SERVICES_DIR selects the host agent's discovery directory. The default is not ~/devctrl.

Run the TypeScript example

The repository includes custom-read-gateway.ts and its service definition. The example exposes exactly GET /v1/status, reading the fixed upstream's GET /api/status. It returns only a recognized status and a numeric version, rejects other methods, paths and query strings, and does not follow redirects. GET /healthz checks the listener, not the upstream account.

Copy both files into the chosen host service directory, replace the definition's repository allowlist, and run the script with Node.js 24.22.1 LTS or a newer patched supported release on the machine where the gateway should live:

# Set this to the service directory for your installation from the table above.
services_dir="$HOME/.config/devctl/hosts/remote-server/services.d"
gateway_private_dir="$HOME/.config/devctl/gateway-secrets/custom-api"
mkdir -p "$gateway_private_dir"
chmod 700 "$gateway_private_dir"
# Generate once; noclobber prevents replacing an existing consumer token.
(umask 077; set -C; node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))' > "$gateway_private_dir/token")

UPSTREAM_ORIGIN='http://127.0.0.1:3100' \
GATEWAY_TOKEN_FILE="$gateway_private_dir/token" \
node "$services_dir/scripts/custom-read-gateway.ts"

This command runs in the foreground for verification. For retained operation, use your host's process supervisor or an independently managed container; do not rely on a foreground shell staying connected. The example uses erasable TypeScript types that Node 24 runs directly. Compile TypeScript that needs transforms to JavaScript, or provide its required runtime yourself.

The sample upstream response is {"status":"ready","version":"1.2.3"}. If that API requires a bearer token, set UPSTREAM_TOKEN_FILE to a private file on the gateway host. Never copy the upstream token into the service definition or a project environment. The incoming gateway token is separate.

By default the gateway listens at 127.0.0.1:18770. For a separate Docker container, set GATEWAY_BIND=0.0.0.0 and publish the port only to the host's loopback address. On Docker Desktop, a native host listener must accept traffic from the host agent's Docker network; configure that listener safely and use host.docker.internal in the definition. 127.0.0.1 inside that agent refers to the agent container, not macOS.

Register and grant access

With the example definition, a host named remote-server publishes the service as host:remote-server:custom-api, with endpoint api. Discovery publishes the service; it does not grant it to a project or start the gateway process.

Select the endpoint and project in Services and grant access with alias custom-api. A tracked project requirement can use the same service identity:

services:
  - service: host:remote-server:custom-api
    endpoint: api
    alias: custom-api
    required: true
    lifecycle: manual

The granted project reaches http://custom-api.devctl.internal:18770/v1/status. Deliver the separate incoming gateway token with an explicit managed secret or FileGrant to approved consumers, and send Authorization: Bearer <token>. Network reachability and authentication are separate requirements. The upstream credential stays with the gateway.

The sample shares one status operation across its approved consumers. If an API serves different private data per project, enforce that scope in the gateway too. HTTP endpoints may opt into injectProjectIdentity: true; the fixed-target proxy supplies trusted project identity. Do not trust identity headers on an unprotected direct listener or assume that a route grant filters upstream data.

Optional lifecycle management

A definition can add lifecycle with executable start, health and stop scripts using the existing json-v1 contract. Scripts read private runtime state from stdin and return bounded JSON on stdout. Health returns running, healthy and an optional safe message. autoStart: on-demand starts for active consumer grants, rather than the first incoming HTTP request.

Scripts execute in the host agent's environment, not a coding session or automatically in the native SSH shell. Their executables and dependencies must be available there. Keep scripts beneath the service directory and use them to manage an independent host service/container if it should survive host agent replacement. See the lifecycle contract and examples.

Gateways and lifecycle scripts are trusted operator code. Keep credentials out of code, YAML, images, reusable snapshots, lifecycle JSON and diagnostic output. Only return the data an approved consumer should see; validate methods, paths, resource identifiers, request sizes and upstream responses. Keep health checks bounded and distinguish a live listener from valid upstream authorization.