Skip to main content
Local harnest serve listens on 127.0.0.1:1907 with the playground enabled by default. Compiled launchers serve the agent API without the playground. You do not need a separate server configuration file. Add a root server: section to config.yaml only when you want to change a default. Each section and setting is optional:
config.yaml
This changes the port and request-size limit. Every other server setting retains its default.

​
Enable WebSockets

AG-UI is enabled by default. Set server.agui: false to disable POST /agui and remove its discovery entry. It accepts a boolean or an exact environment reference such as ${AGUI_ENABLED}. Embedding applications can pass agui_enabled=False to create_fastapi_app or create_neutral_app. Rebuild and restart after changing authored settings. Set live: true under server to enable live WebSocket connections:
config.yaml
This enables WS /live on the same host and port as HTTP, such as ws://127.0.0.1:1907/live. It does not open a second listener or require another port. Use wss:// when your deployment terminates TLS. With live: false, HTTP and SSE remain available, but all WebSocket routes are disabled. The playground hides its live transport.

​
Hide API documentation

config.yaml
This disables /docs, /redoc, /openapi.json, and /openapi.yaml, and removes their links from the playground, /agent, and startup output. The agent API still works. Hiding documentation is not authentication; protect the API separately for deployment. With openapi: true, local and compiled servers expose both schema formats. Local startup prints their URLs.

​
Server properties

See the server settings reference for all properties and defaults. Configure only the values your deployment needs; omitted settings retain their defaults.

​
Environment references

Use exact ${NAME} values when a setting comes from the server’s startup environment:
config.yaml
Compilation preserves these references. The standalone launcher resolves and type-checks them at startup. Partial interpolation and missing, empty, or invalid values fail. Boolean environment values must be true or false.

​
Concurrency and throughput

server.http.maxConcurrentRequests limits concurrent in-flight requests in each server process. It counts requests in progress, not open connections, so idle keep-alive connections do not use slots. The limit applies to Harnest’s routes and ADK’s native routes alike. Requests over the limit receive HTTP 503 Service Unavailable. With harnest serve, Playground page and file loads (GET / and /_harnest/*) do not count toward the limit. Playground actions, such as evaluation runs, still count. This is an admission limit, not a requests-per-second rate limit or a throughput promise. Tune concurrency against model quotas and downstream capacity; raising it can worsen saturation. Choose the value from load tests that use representative agents and production dependencies. Scale replicas separately through your deployment platform.

​
Configuration boundary

Legacy spec.resources and spec.scaling do not override HTTP settings. See retired settings. Use harnest-deployment.yaml for infrastructure limits and replicas.
allowRemote: true only permits the bind. It does not add authentication, TLS, or network policy.
Explicit serve flags temporarily override server settings.

​
Existing projects with server.yaml

Existing authored server.yaml files remain supported. Files without a live field retain their previous WebSocket access; set live: false in that file to disable it. To consolidate a project:
  1. Move its http, limits, and playground mappings under a root server: section in config.yaml. Add live: true there if you want to retain WebSocket access. You can omit other settings that match the defaults.
  2. Leave out the legacy file’s apiVersion and kind fields.
  3. Remove the authored server.yaml and compile again.
Harnest rejects projects that declare both config.yaml → server and an authored server.yaml, even if the inline section is empty. Choose one source rather than relying on precedence. New projects and upgrades do not create a server defaults file.

​
Compiled artifacts

Compilation writes server.yaml beside the launcher. Operators can replace it and restart, or edit project configuration and recompile. Python applications that directly embed create_fastapi_app or create_neutral_app can pass live_enabled=False to disable WebSockets. These embedding APIs keep their historical True default; the standalone launcher always passes its resolved server setting. Pass agent_principal_required=True to apply the same invocation grant policy when embedding the server directly.