> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Server configuration

> Override standalone server defaults in your project config.

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:

```yaml config.yaml theme={null}
# Alongside apiVersion, kind, metadata, and spec:
server:
  http:
    port: 9090
  limits:
    maxRequestBytes: 10MiB
```

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:

```yaml config.yaml theme={null}
server:
  live: true
```

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

```yaml config.yaml theme={null}
server:
  openapi: false
```

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`.

| Property                     | Controls                                                                       | Default     |
| ---------------------------- | ------------------------------------------------------------------------------ | ----------- |
| `live`                       | Enable WebSocket connections                                                   | `false`     |
| `openapi`                    | Expose API documentation and JSON/YAML spec resources                          | `true`      |
| `agentPrincipal`             | Require custom agent invocations to bind runtime grants                        | `optional`  |
| `http.host`                  | Bind host                                                                      | `127.0.0.1` |
| `http.port`                  | Bind port                                                                      | `1907`      |
| `http.allowRemote`           | Consent for a non-loopback bind                                                | `false`     |
| `http.requestTimeoutSeconds` | Request timeout in seconds                                                     | `300`       |
| `http.maxConcurrentRequests` | Active in-process requests (`1`–`100000`)                                      | `8`         |
| `limits.maxRequestBytes`     | HTTP body and WebSocket frame size                                             | `1MiB`      |
| `playground.enabled`         | Allow the UI supplied by local `harnest serve`; does not add UI to deployments | `true`      |

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:

```yaml config.yaml theme={null}
server:
  live: ${LIVE_ENABLED}
  http:
    port: ${PORT}
  playground:
    enabled: ${PLAYGROUND_ENABLED}
```

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

| Put in `config.yaml` → `server` | Configure elsewhere         |
| ------------------------------- | --------------------------- |
| Bind address                    | Authentication              |
| Timeout and concurrency         | TLS                         |
| Request-size limits             | Secrets                     |
| Playground toggle               | Durable storage             |
| Local operator settings         | Replicas and network policy |

`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](/docs/harnest/build/project-configuration#retired-resource-and-scaling-fields) when cleaning up old configs. Configure deployment resource limits and replicas in [`harnest-deployment.yaml`](/docs/harnest/runtime/serving/provisioning); configure standalone HTTP limits here.

<Warning>
  `allowRemote: true` only permits the bind. It does not add authentication, TLS, or network policy.
</Warning>

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.