Hosting a local gateway

Run a local gateway in your own environment to give a backend direct access to RPC providers. You can also put your own HTTPS endpoint in front of it for browser applications. In both cases, you operate the gateway and control its identity, funding, and access.

Start the gateway

Install Direct on the host and run the RPC client under a dedicated operating-system account. Choose a configuration folder that belongs to that account:

direct rpc --headless --config /var/lib/direct-rpc --port 1337

An explicit --port must be available; only the default port falls back to an automatically selected one when it is occupied. Create the folder with the appropriate ownership before starting a service. The command must run as the account that owns it. The gateway listens on loopback by default, so a backend on the same host can use:

http://127.0.0.1:1337/service/ethereum

HTTP and WebSocket share the chain path: use ws://127.0.0.1:1337/service/ethereum for WebSocket access. Replace ethereum with the endpoint name from Supported chains. The default port is 1337; when no port is explicitly selected and that port is occupied, use the address reported by the client.

Blockchain calls go to /service/<chain>. /direct is the local management API and /direct/status is a health endpoint; neither is an RPC URL for your blockchain library. Keep management routes private when exposing an application endpoint.

The local gateway applies host and origin restrictions to prevent websites from spending through it. Browser applications should use a managed gateway or the authenticated HTTPS deployment described below.

Keep the process running with your environment's service manager. Allow the outbound traffic needed to reach providers, including UDP. Use a separate configuration folder for each independently operated client.

Preserve the client's identity

On first start, the client generates a random 32-byte seed and writes it to a file named seed in the configuration folder. It derives its identity from that seed. Starting again with the same seed restores the same public key; starting without it generates a new identity.

Without an explicit --config, the default folders are:

Platform	Configuration folder
Linux	$XDG_CONFIG_HOME/direct, or ~/.config/direct when XDG_CONFIG_HOME is not set
macOS	~/Library/Application Support/direct
Windows	%APPDATA%\direct

DIRECT_CONFIG can also select the folder; --config takes precedence. An absolute path makes service and container deployments easier to reason about.

New configuration folders are created with Unix permissions 0700, and new seed files with 0600. Existing folders, restored backups, and mounted volumes must also be restricted to the account running Direct. On Windows, restrict access using the folder's access-control settings.

Anyone who obtains the seed can impersonate the client. Keep it out of source control, public images, application logs, and support reports. Protect backups as carefully as the running copy.

Deploy with persistent storage

Mount the configuration folder on persistent storage when the process runs in a container or is replaced during deployment. For the command above, that means preserving /var/lib/direct-rpc, including its seed file.

A writable container filesystem alone is not persistent storage: replacing the container may remove it. Confirm the volume is attached and readable by the process before sending traffic. Restart the gateway and compare its public key with the one reported before the restart.

Reusing the identity does not restore every piece of runtime state. Connections must be re-established. Use separate identities for independent replicas rather than mounting one seed into several concurrent gateways.

Supply a seed without persistent storage

A deployment with no persistent volume can obtain the same seed from its secret manager on every start. Inject it into the process environment rather than placing it in an image or committing it in a deployment manifest.

With DIRECT_SEED supplied by your deployment platform, start the gateway normally:

direct rpc --headless --config /tmp/direct-rpc --port 1337

The process uses that seed to establish its identity even when the configuration folder is temporary. Inject the same secret after each replacement and check that the public key stays unchanged. Do not use a conflicting persisted seed and environment seed in the same deployment.

Environment injection avoids dependence on a persistent seed file, but the value is still private key material. Restrict access to deployment secrets and process diagnostics, and never print the environment into logs.

Fund the gateway

Run the gateway as a device of your account, with a server key, so it pays from your account's balance on Base without being able to withdraw it. See Managing payments and spending.

The client's identity seed is not a wallet recovery phrase. Restoring the same public key establishes who the client is; it does not independently establish permission to spend a wallet's funds.

Serve your backend

A backend on the same host can call the loopback endpoint directly. Keep management requests to /direct and /direct/status within the trusted deployment environment.

In a container deployment, 127.0.0.1 refers to that container's network namespace. Use a shared network namespace for loopback access, or expose the gateway only on a private network restricted to the application and proxy. Binding to 0.0.0.0 is not an authentication mechanism.

Serve a browser application through your own endpoint

Your frontend can use an HTTPS URL that you operate, while the gateway stays on loopback behind a reverse proxy. This gives browser applications access without requiring Direct's managed gateway. You are responsible for the public endpoint's availability, TLS, authorization, and spending exposure.

Configure the public endpoint to:

1. Authenticate callers using your application's session or access policy.
2. Apply per-user or per-application usage limits.
3. Proxy only the blockchain paths you intend to offer.
4. Handle browser origins and CORS at the proxy.
5. Leave the local management API inaccessible from the public endpoint.

An origin allowlist is useful for browser policy, but a non-browser caller can forge an origin. A key embedded in frontend code is also public. Enforce access and abuse limits independently of either assumption.

Example HTTP proxy path

The following Nginx locations belong inside an HTTPS server you have already configured. They expose only Ethereum RPC. The example assumes your own authorization service answers at 127.0.0.1:9000/rpc/authorize, returning 2xx for allowed callers and 401 or 403 otherwise. That service is part of your deployment, not an endpoint provided by Direct.

location = /ethereum {
    auth_request /_rpc_authorize;
    proxy_pass http://127.0.0.1:1337/service/ethereum;
    proxy_set_header Host 127.0.0.1:1337;
    proxy_set_header Origin "";
    proxy_set_header Authorization "";
    proxy_set_header Cookie "";
}

location = /_rpc_authorize {
    internal;
    proxy_pass http://127.0.0.1:9000/rpc/authorize;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

location / {
    return 404;
}

Nginx's authorization subrequest module must be enabled. It checks access before forwarding the RPC request. The proxy then sets the upstream host and removes the browser origin because the local gateway expects trusted local requests. Apply and validate your browser origin policy before removing that header; see Nginx's proxy header documentation.

This fragment is an HTTP routing example, not a complete TLS, CORS, or rate-limit configuration. Configure those policies for your domain and application. For WebSocket subscriptions, also configure authenticated upgrades and appropriate connection timeouts; HTTP proxying alone does not establish subscription support.

Check the deployment

First send a request from the backend to the local gateway. Then test the public endpoint with an authorized caller, and verify that an unauthenticated caller is rejected. Check that /direct, /direct/status, and unintended chain paths cannot be reached through the public hostname.

Finally, replace or restart the gateway and confirm that its identity is unchanged, funding is usable, and the application can make requests again. Troubleshooting requests covers diagnosing a failed call.

Check a running gateway

Use the printed address when connecting applications; a running process does not by itself confirm that a provider is available. In headless deployments, inspect status and connections with:

direct rpc status get --json
direct rpc peers list --json
direct rpc activity list --json

Recent activity is held in memory and clears on restart. Retain application logs for longer investigations, and follow Troubleshooting requests when calls fail.