Deployment

A deployment is the gateway somewhere callers can reach and the agent inside the on-prem network. You copy two binaries; neither needs Docker, a Go toolchain, a source checkout, or database client libraries.

Supported platforms

Older versions may work but are not covered. Test the exact release on an older legacy host before relying on it.

On Linux, folder sources, file saving, and code filesystem access need kernel 5.6 or later. Saving files also has filesystem requirements.

Install from a release

Each GitHub release has one archive per platform, all containing both binaries, INSTALL.md, and incomplete gateway.env.example and capability.yaml.example templates. The links download the latest release:

For a specific version, use https://github.com/viewlegacy/onprest/releases/download/vX.Y.Z/<asset> or pick one on the GitHub Releases  page. The separate onprest-quickstart.tar.gz holds the Quick Start files with public credentials and is not for production.

To verify a download, save SHA256SUMS from the same release next to it:

sha256sum --check --ignore-missing SHA256SUMS   # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
gh attestation verify onprest-linux-amd64.tar.gz --repo viewlegacy/onprest

On Windows, compare (Get-FileHash onprest-windows-amd64.zip).Hash with the line in SHA256SUMS.

Then follow the bundled INSTALL.md. Always deploy the gateway and agent from the same release.

Set up a new customer

1. Generate an agent key pair with onprest-gateway create-agent-secret.
2. Generate API keys with onprest-gateway create-key.
3. Write the customer’s gateway.env, start a dedicated gateway, and terminate TLS in front of it.
4. Put onprest-agent and a capability.yaml on the on-prem host. Fill in the gateway URL (wss://.../ws/agent), the agent private key, the sources, and the capabilities.
5. Run onprest-agent validate --config PATH.
6. Start the agent, or install it as a service.
7. Check /healthz, /openapi.json, and one REST and one MCP call.

Run the binaries

set -a
. ./gateway.env
set +a
./onprest-gateway

./onprest-agent --config ./capability.yaml

On Windows, set the gateway’s variables in the process or service environment:

$env:GATEWAY_AGENT_PUBLIC_KEY = '<generated-agent-public-key>'
$env:GATEWAY_API_KEYS_JSON = '[{"name":"operator","key_hash":"<generated-key-hash>","capabilities":["get_customer"]}]'
.\onprest-gateway.exe

.\onprest-agent.exe validate --config .\capability.yaml
.\onprest-agent.exe --config .\capability.yaml

To run the agent as a systemd, launchd, or Windows service, follow Capability Changes. Service installation does not enable start on boot; configure that with the host OS if you need it. Under a service manager, the agent’s stdout and stderr go where the manager sends them (on macOS, /var/log/onprest-agent.stdout.log and /var/log/onprest-agent.stderr.log); the detailed log stays in onprest-agent.log next to the binary.

Timeouts and uploads

A call with uploads or downloads has up to three phases: receiving input (runtime.transfer_timeout, default 60s), running (policy.timeout), and sending a direct or inline file (runtime.transfer_timeout again). Set client and proxy timeouts to cover all three, and let a proxy pass multipart bodies through unchanged and up to GATEWAY_MAX_FILE_REQUEST_BODY_BYTES.

For capabilities that read or save files, create the folders with the permissions their access setting needs before starting the agent. Keep them separate from the agent’s spool and identity directories.

Docker

Docker is optional. Build the images from a checkout of the repository; release archives do not include the Dockerfile.

docker build --build-arg TARGET=gateway --build-arg VERSION=x.y.z -t onprest-gateway .
docker build --build-arg TARGET=agent --build-arg VERSION=x.y.z -t onprest-agent .

The agent image runs as UID/GID 65532:65532. Mount the configuration read-only, and give the agent a persistent identity directory and a separate spool directory that this user owns:

runtime:
  identity_dir: /var/lib/onprest/identity
  spool_dir: /var/lib/onprest/spool

mkdir -p "$PWD/agent-identity" "$PWD/agent-spool"
sudo chown 65532:65532 "$PWD/agent-identity" "$PWD/agent-spool"
sudo chmod 700 "$PWD/agent-identity" "$PWD/agent-spool"
docker run --rm \
  -v "$PWD/capability.yaml:/config/capability.yaml:ro" \
  -v "$PWD/agent-identity:/var/lib/onprest/identity" \
  -v "$PWD/agent-spool:/var/lib/onprest/spool" \
  onprest-agent --config /config/capability.yaml

Keep the identity volume when you recreate the container. Use one spool per agent container. Addresses in capability.yaml must be reachable from inside the container, and onprest-agent service install does not apply in containers. When an env file is passed to Docker, make sure GATEWAY_API_KEYS_JSON keeps its $ characters.

The agent’s detailed log is /app/onprest.log inside the container and is deleted with it; to keep it, run without --rm and copy it out with docker cp.

Database TLS certificate rotation

The agent reads database CA and client certificate files when it starts. Rotate with an overlap so both old and new material work until the new connection is confirmed:

• New private CA: deploy a CA bundle with both the old and new CA, validate, and restart the agent. Switch the database server certificate, confirm a capability call, then remove the old CA, validate, and restart again.
• New client certificate: make the database accept both the old and new certificate (or CA), replace the agent’s certificate and key together, validate and restart, confirm a capability call, then revoke the old one.

Retire the old material only after a capability call succeeds on the new one. If the database cannot accept both at once, schedule a maintenance window.