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.