Policies
How organization and project policies restrict environments, agent tools, providers, registries and connections across kosem.
Policies set hard boundaries on what can be done in an organization's projects, regardless of a caller's role. While IAM roles decide who can act, policies decide what is allowed at all — binding Owners, service accounts and agents alike. Viewing policies is available on every plan; editing them requires the Team or Enterprise plan (Limits and quotas).
How policies combine
Policies compose directly on top of your organization's plan limits. An organization's policy applies to every project inside it, and a project can only tighten what the plan and organization allow:
- Boolean policies (such as turning off the LLM Gateway or public sites) are enforced if either the organization or the project enforces them.
- Allow-list policies (such as allowed agent tools) take the intersection of both levels. When an allow-list is set, new values added to kosem later stay off until added to the policy.
- Maximum policies (such as largest environment disk or retention windows) take the lowest of kosem's limit, the organization's plan entitlement, the organization's policy and the project's policy. When a plan entitlement is the binding ceiling, the policy's effective source is
planand exceeding it answersPLAN_REQUIREDrather thanPOLICY_VIOLATED.
If an organization or project sets a looser policy than the level above, kosem keeps that value inactive until the ceiling above rises.
Guardrail policies (Settings › Policies)
| Policy | Constraint ID | Type | What it restricts |
|---|---|---|---|
| Most vCPUs | environments.maxVcpus | Max (1–8) | Maximum vCPUs per environment (plan cap: 2 on Hobby, 8 on Pro/Team) |
| Most memory | environments.maxMemoryGib | Max (1–52) | Maximum GiB of memory per environment (plan cap: 8 on Hobby, 52 on Pro/Team) |
| Largest disk | environments.maxDiskGib | Max (10–500) | Maximum GiB of disk per environment (plan cap: 50 on Hobby, 500 on Pro/Team) |
| Longest idle time | environments.maxIdleTimeout | Max (15–240 min) | Longest idle timeout before an environment stops; lowers running ones at once |
| Turn off projects' own registries | environments.projectRegistriesDisabled | Boolean | Prevents projects from adding container registries of their own |
| Allowed tools | agents.allowedTools | Allow-list | Tools agents can use in the project |
| Most model calls between messages | agents.maxModelCalls | Max (10–2,000) | Maximum model calls an agent makes after a message before pausing |
| Longest agent access grant | agents.maxGrantTtl | Max (1–720 hr) | Longest lifetime allowed for an agent's access profile or secret grant |
| Turn off the LLM gateway | llmgateway.disabled | Boolean | Refuses all LLM Gateway requests and agent model calls in the project |
| Turn off projects' own providers | llmgateway.projectProvidersDisabled | Boolean | Blocks project-owned providers and stops serving models through ones added earlier |
| Turn off projects' own connections | connections.projectConnectionsDisabled | Boolean | Prevents projects from connecting GitHub, Google Cloud or AWS accounts of their own |
| Turn off public sites | sites.publicDisabled | Boolean | Prevents making sites public; sites already public stay public until made private |
Retention policies (Settings › Data retention)
Retention constraints share the same policy API and monotonic inheritance (tagged category: "retention"), and appear together in Settings › Data retention alongside audit log and grace-period retention:
| Policy | Constraint ID | Bounds | Plan defaults (Hobby / Pro / Team) | What it deletes past the window |
|---|---|---|---|---|
| Agent and file retention | agents.retentionDays | Max (7–365 days) | 90d / 365d / Unlimited | Inactive agents, transcripts and attached files (daily totals stay) |
| Site retention | sites.retentionDays | Max (7–365 days) | 30d / Unlimited / Unlimited | Inactive sites and their published versions |
| Longest kept stopped | environments.maxStoppedTtl | Max (24–720 hr) | 7d / 30d / Unlimited | Stopped environments and disks; applies at next stop |
| Request log retention | llmgateway.requestLogDays | Max (1–3,650 d) | 7d / 30d / 90d | Individual LLM Gateway request records (daily usage totals stay) |
Enforcement
Most policies apply at admission time (when resources are created, updated or started) without deleting existing resources. Three take effect right away on existing work:
- Turn off the LLM gateway and Turn off projects' own providers stop matching model requests immediately.
- Allowed tools and Most model calls between messages apply to running agents on their next model call.
- Longest idle time lowers the idle timeout of existing environments immediately.
Any request blocked by a policy fails with failed_precondition and reason POLICY_VIOLATED (Errors), naming the constraint and whether the organization or project set it.
Why it works this way
- Separation from product admins. Product admins (Agents Admin, Environment Admin, LLM Gateway Admin) manage day-to-day resources, while Owners and Policy Admins control guardrails.
- Monotonic tightening. Central security teams can enforce an organization-wide ceiling with confidence that no project Owner can override it.