Proxy Settings

Proxy Settings control two container-wide knobs: is the proxy on, and what is the default policy when no rule matches. enable_proxy and default are the two root fields of the container’s proxy-permissions document; the /proxy/settings endpoints are a narrow, ETag-gated read/write view onto them.

GET /api/v1/containers/{id}/proxy/settings → data

{
  "enable_proxy": true,
  "default": "allow",
  "file_version": 3,
  "etag": "file:v3"
}

• enable_proxy — boolean. When false, the proxy refuses to route traffic for this container regardless of what’s in the permissions document: new requests to its service URLs are denied with 403, evaluated before groups, rules, and default. Useful as a per-container kill-switch. It cuts reachability — it does not bypass access control. This container-level value overrides the project-level one in both directions, so it is the reliable place to disable a single container.
• default — "allow" or "deny". The fallback decision when no group in the permissions document matches the incoming request.

Why a separate endpoint?

The permissions document is the large, frequently-edited policy file (groups, per-program access, hooks). Settings is the small, rarely-edited switch. A dedicated endpoint means you can flip enable_proxy without re-sending a multi-kilobyte permissions JSON. Both surfaces read and write the same document, so they share one file_version — a settings write bumps the permissions ETag and vice versa. Re-read before your next conditional write.

---

API surface

Verb	Path	What it does
GET	/api/v1/containers/{id}/proxy/settings	Return current enable_proxy + default + ETag
PUT	/api/v1/containers/{id}/proxy/settings	Update one or both fields. Requires If-Match: file:v<N>.

The update body accepts either field independently — you can flip enable_proxy without touching default or vice versa. This operation is also reachable via PATCH on the same path; the CLI and SDK below both issue PUT.

Via the Hoody CLI

# Read current proxy root settings (enable_proxy, default) and the file_version for If-Match
hoody containers proxy settings get <container-id> -o json

# Update proxy root settings — pass at least one of --default / --enable-proxy,
# plus the --if-match ETag read above
hoody containers proxy settings update <container-id> --default deny --if-match file:v<N>

# --enable-proxy is presence-only: it can turn the proxy on, never off.
# To disable, use the SDK or HTTP with enable_proxy: false.
hoody containers proxy settings update <container-id> --enable-proxy --if-match file:v<N>

Via the SDK (TypeScript)

const current = await client.api.proxyDiscovery.getContainerProxySettings(containerId);
// current.data: { enable_proxy: true, default: 'allow', file_version: 3, etag: 'file:v3' }

await client.api.proxyDiscovery.updateContainerProxySettings(containerId, { enable_proxy: false }, { ifMatch: current.data.etag });

Optimistic concurrency

Mutating calls require an If-Match: file:v<N> header matching the most recent file_version. Omit the header entirely and the server returns 428 Precondition Required; send a stale version (the file has moved since your last read) and it returns 412 Precondition Failed with message: etag_mismatch — re-read, re-apply your change, and retry. This mirrors the concurrency contract used by permissions and hooks.

---

When to use Settings vs. Permissions

Task	API surface
Turn the whole proxy off for a container	Settings — enable_proxy: false
Set the catch-all allow/deny when no group matches	Settings — default
Define who (IP, JWT, password, token, hoody-identity) can call what program	Permissions
Attach MITM scripts to matching traffic	Hooks
Expose a container on a custom subdomain	Aliases

---

Scope

Proxy Settings are container-level only. There is no project-level settings endpoint; the per-container enable_proxy / default is the authoritative source for a given container. Project-level default policy can be set via the project’s proxy permissions document.

---

Further reading

• Proxy Permissions — the larger document that lists groups and per-program access.
• Proxy Hooks — attaching MITM scripts that run inside your own hoody-exec.
• Hoody Proxy overview — how Settings, Permissions, Hooks, and Aliases fit together.