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

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. New projects default to live: false. HTTP requests and SSE streams remain available. When live is disabled, the server rejects all WebSocket upgrades, including native ADK and custom WebSocket routes. /agent omits the live endpoint, and the playground disables its Live transport choice.

​
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 the default openapi: true, both spec formats are available as HTTP resources. harnest serve . prints the Swagger URL and both spec URLs using the effective bind address and port. The compiled launcher uses the same policy.

​
Server properties

All property paths below are relative to server in config.yaml. Unknown fields, invalid types, and out-of-range values fail during compilation. Omit a field to inherit its default; null does not mean “use the default.” Set agentPrincipal: required when every custom HTTP route must pass an application-authorized agent_principal= to AgentInvoker. An omission then fails before Harnest creates a session. Neutral Harnest routes do not construct application-specific grant sets and are unaffected by this setting.

​
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 how many agent requests can execute concurrently in each server process. It is an admission limit, not a requests-per-second rate limit or a throughput promise. Actual throughput depends on model latency and quotas, Agent Tools, MCP services, storage, CPU, memory, and replica count. Increasing the value permits more active work but can reduce reliability when a downstream dependency is already saturated. Requests beyond available capacity may wait or be rejected by the serving layer. Choose the value from load tests that use representative agents and production dependencies. Scale replicas separately through your deployment platform.

​
Configuration boundary

spec.resources and spec.scaling are silently ignored in agent configuration. They never override server.http and do not need to be removed for an existing project to load. See retired settings when cleaning up old configs. Configure deployment resource limits and replicas in harnest-deployment.yaml; configure standalone HTTP limits here.
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 a complete, versioned server.yaml beside harnest-agent. The launcher reads that generated operational copy. Operators can replace it and restart the server without changing the compiled agent source; the authored config.yaml remains part of the source digest. Normally, edit your project config and compile again. 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 custom-route principal policy when embedding the server directly.