Summary#
Your organization's policy is a floor you build inside. The platform enforces each rule where it binds, at run time or
at deploy, whoever writes the code. osy policy shows the rules that apply to the app you are in (osy policy egress, osy policy packages, osy policy secrets, osy policy models, osy policy agents, osy policy audit,
osy policy settings for one kind; --json for a program or for Claude), and
osy policy request asks for an exception where a rule allows one. A policy admin decides.
This page is generated from the platform's catalogue of what a policy controls; a test fails when the two differ.
Description#
What does a refusal tell you?#
A refusal has two forms. The short form is the refusal's message: it is what a door answers anyone signed in, and
what your app's own code sees in a catch. It names what was refused and the rule's reason, and nothing else of the
policy. The builder explanation is printed by osy (a deploy, a compile, a test) to a member of the
organization who builds its apps: which rule, what it allows that matters here, how to comply, where to read more,
and one line saying whether an exception may be asked for. Each example below shows both, made by the platform's own
code from the example rule.
How do you ask for an exception?#
When the explanation's last line says you can ask, run the command it gives, with the real reason:
$ osy policy request egress.hosts api.stripe.com --why "Payments for the shop go through Stripe"The rule's key and the subject are as the explanation gives them. A machine acting for someone names them with
--for <address>, and an agent says what it is with --agent "Claude Code". A policy admin decides; until then
the subject stays refused. A rule the organization made hard allows no exceptions, and the explanation says so.
Never route around a rule: moving a call into another package, renaming, splitting or re-hosting code, or writing a governed value somewhere else is refused too, and works against the people who set the rule.
When a rule limits outbound hosts: egress.hosts#
For example: api.stripe.com is outside your organization's outbound hosts: calls to it are refused at run time.
Declared by platform. Value: host-list. Mode: lock.
An example rule.
egress.hosts = api.example.com, -tracker.example, [email protected]Each entry is written one of these ways:
host: allowed: while the value names any, the organization's applications reach only these (a ceiling).-host: blocked: refused to every application and every package, whatever else allows it.host@Package: reachable only by code of the package NAMED so (its full name, matched exactly), and only where the application grants it the host; refused to the application's own code and to every other package. Not an allowed host: it makes no ceiling by itself, and a blocked host stays blocked.
The code it affects: every outbound call the application's own code and its packages make (Http, a fetch from its pages).
Where it binds: an application's outbound call (its own code and a package's), Http.Refusal, the page's Content-Security-Policy, the operator's review. A signed-in osy validate warns early, only for someone who can read the organization's policy; the CLI never decides, and each call is judged when it is made.
The short form (the refusal's message):
This app tried to reach `api.stripe.com`, and your organization's policy does not allow it: "the reason your organization gives".The builder explanation (what osy prints to a builder):
`api.stripe.com` is outside your organization's outbound hosts: calls to it are refused at run time.
Allowed hosts: `api.example.com`.
Call an allowed host, or a host your organization gives a package (`Acme.Mail` reaches `api.mail.example`).
More: `osy policy egress`.
You can ask for an exception: `osy policy request egress.hosts api.stripe.com --why "…"` (Claude: the same; say who you act for). A policy admin decides; until then this stays refused.How to comply: Call an allowed host, or a host your organization gives a package (Acme.Mail reaches api.mail.example).
How to ask: a new rule of this kind allows exceptions unless the organization makes it hard. Where the explanation says you can ask: osy policy request egress.hosts <host> --why "…". osy policy egress shows the rules of this kind that apply to your app.
When a rule approves package versions: packages.approved#
For example: Acme.Mail 1.0.0 (sha256:…) is not approved.
Declared by platform. Value: package-list. Mode: lock.
An example rule.
packages.approved = [email protected]=sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08Each entry is written one of these ways:
Name@Version=sha256:hex: approves the package of that full name at that exact version with that archive (its content address); another version or another hash is not approved. For a platform kit the hash is the canonical hash of its files that its release records and shows (OP-K1d4), not the hash of the archive's bytes, which is an uploaded package's.
The code it affects: the packages the application pins in its lock file (osyrin.lock), each by name, version and hash.
Where it binds: Admin's deploy: osy deploy's ask (a first deploy included), each environment that follows a deploy, and an attempt to run a restored copy on its older version refuse a package unless an entry approves its exact name, version and hash. The CLI says what each package reaches. A package that reaches nothing needs no approval where the zone's release declares it checks claims against the bytes; a follow and a restore still need its entry. Any other package, the application's own workspace packages included (their hash changes with each build), needs its own entry. osy deploy and a signed-in osy validate warn early, only for someone who can read the organization's policy; the CLI never decides, and Admin's ask judges every deploy. A platform kit is judged like any other, by the canonical hash its release records and shows, never the hash of an archive's bytes. A single-node platform's compile (a dry run included), git deploy, osy test and osy debug-test refuse the same way, judging each package by what its own bytes reach, so there a package that reaches nothing needs no entry. Not yet at a zone's own build, an automatic rollback, or a platform kit the release carries. A release's move back is not judged: it rebuilds nothing and serves the build that release already ran, which was judged when it was deployed.
The short form (the refusal's message):
This deploy carries `Acme.Mail` 1.0.0, which your organization's policy does not allow: "the reason your organization gives".The builder explanation (what osy prints to a builder):
`Acme.Mail` 1.0.0 (sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08) is not approved.
Approved versions of `Acme.Mail`: 0.9.2.
Pin an approved version (`[email protected]`), or ask a policy admin to approve the version you pin.
More: `osy policy packages`.
You can ask for an exception: `osy policy request packages.approved [email protected]=sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 --why "…"` (Claude: the same; say who you act for). A policy admin decides; until then this stays refused.How to comply: Pin an approved version ([email protected]), or ask a policy admin to approve the version you pin.
How to ask: a new rule of this kind allows exceptions unless the organization makes it hard. Where the explanation says you can ask: osy policy request packages.approved <package>@<version>=sha256:<hash> --why "…". osy policy packages shows the rules of this kind that apply to your app.
When a rule requires a package: packages.required#
For example: This app does not compose Osysharp.Audit.
Declared by platform. Value: package-names. Mode: lock.
An example rule.
packages.required = Osysharp.AuditEach entry is written one of these ways:
Name: every application of the organization must compose the package of that full name, directly or through another package, at any version.
The code it affects: the packages the application composes, directly or through another package.
Where it binds: Admin's deploy, a follow, a restore: osy deploy's ask (a first deploy included), each environment that follows a deploy, and an attempt to run a restored copy on its older version refuse an application that does not compose every package the rule names, anywhere in its package graph, at any version (a platform kit counts when the build pins it), and a version whose packages are not known. A package of that name meets it; pair it with packages.approved to say which bytes. The names judged are the ones the deploy claims, and a zone's build refuses a deploy or a follow that claims a package its build does not compose; a follow is held to the required names of the deploy it follows and the zone's view; a restore attempt is judged on the names its deploy claimed, not on what the zone composed. Applications already running go on running until their next deploy, and a deploy asked for before the rule came into force is still served. A signed-in osy validate warns early, only for someone who can read the organization's policy; the CLI never decides, and Admin's ask judges every deploy. Not yet: single servers, an automatic rollback or a release's move back.
The short form (the refusal's message):
This deploy is missing packages your organization requires: Osysharp.Audit.The builder explanation (what osy prints to a builder):
This app does not compose `Osysharp.Audit`.
Add it: write `use Osysharp.Audit@<major>;` in your `app { }` manifest (`osy search Osysharp.Audit` prints the line), then run `osy lock`.
More: `osy policy packages`.
You can ask for an exception: `osy policy request packages.required Osysharp.Audit --why "…"` (Claude: the same; say who you act for). A policy admin decides; until then this stays refused.How to comply: Add it: write use Osysharp.Audit@<major>; in your app { } manifest (osy search Osysharp.Audit prints the line), then run osy lock.
How to ask: a new rule of this kind allows exceptions unless the organization makes it hard. Where the explanation says you can ask: osy policy request packages.required <package> --why "…". osy policy packages shows the rules of this kind that apply to your app.
When a rule limits the secrets written at run time: secrets.runtime#
For example: ApiTokens may not be written at run time under your organization's policy.
Declared by platform. Value: secret-list. Mode: lock.
An example rule.
secrets.runtime = ModelKeys, -billing/PayoutKeysEach entry is written one of these ways:
Name: allowed: while the value names any, the organization's applications write at run time only the keyed secrets named (a ceiling).app/Name: allowed for the application with that slug only.-Name: blocked: no application writes that keyed secret at run time, whatever else allows it.-app/Name: blocked for the application with that slug.-*: no keyed secret of any application is written at run time.
The code it affects: the keyed secrets the application declares (new Secret("ModelKeys") { Keyed = true, … }) and the pages and REST calls that write their values.
Where it binds: every write of a keyed secret's value at run time — from the application's page (SetFor) and from its REST door — is judged when it is made, before the value is sealed; a refused write stores nothing and is logged. Removing a value (a retire, in the application or from Admin) is never refused: it cannot widen anything.
The short form (the refusal's message):
`ApiTokens` may not be written at run time under your organization's policy: "the reason your organization gives".The builder explanation (what osy prints to a builder):
`ApiTokens` may not be written at run time under your organization's policy.
The rule names: `ModelKeys`, `-billing/PayoutKeys`.
Write only the keyed secrets your organization allows, or ask a policy admin to allow this one (`ApiTokens`, or `your-app/ApiTokens` for this application only).
More: `osy policy secrets`.
No exception binds secrets.runtime: it changes only in a new version of the policy. Ask your policy writers.How to comply: Write only the keyed secrets your organization allows, or ask a policy admin to allow this one (ApiTokens, or your-app/ApiTokens for this application only).
How to ask: a new rule of this kind allows exceptions unless the organization makes it hard. Where the explanation says you can ask: osy policy request secrets.runtime <Secret> --why "…". osy policy secrets shows the rules of this kind that apply to your app.
When a rule keeps audit trails on: audit.surfaces#
For example: EntityAuditRecord is kept on by your organization's policy, whatever app.Audit says.
Declared by platform. Value: surface-list. Mode: lock.
An example rule.
audit.surfaces (lock) = EntityAuditRecord, AuthAuditRecordEach entry is written one of these ways:
EntityAuditRecord: the data-change trail: who changed which row, when, and what.AccessAuditRecord: the log of reads of classified data.WorkflowAuditRecord: the workflow transitions (always written today).AuthAuditRecord: the sign-in trail.
The code it affects: the application's app.Audit settings: a trail's Enabled = false.
Where it binds: every trail writer an application's app.Audit can turn off (the data-change trail, the classified-read log, the sign-in trail) asks whether its trail is on (AuditConfigReader.SurfaceOnAsync, for the change capture and the sign-in and access writers alike), and a trail the rule names is written whatever app.Audit says; an entity's [Audit(None)] does not take its changes out of a data-change trail the rule names; the workflow transitions are always written. A rule that cannot be read, a version whose rules are missing, or a runtime that cannot ask keeps every trail on. Nothing is refused at deploy: the application's own setting is read over.
The short form: none. Nothing is refused under this rule: the platform reads over what the application says.
The builder explanation (what osy prints to a builder):
`EntityAuditRecord` is kept on by your organization's policy, whatever `app.Audit` says.
The rule keeps on: `EntityAuditRecord`, `AuthAuditRecord`.
Leave the trail on: your organization's policy writes it whatever `app.Audit` says.
More: `osy policy audit`.
This rule allows no exceptions.How to comply: Leave the trail on: your organization's policy writes it whatever app.Audit says.
How to ask: you cannot: an audit rule never allows an exception (your organization's policy admin cannot save one), because an audit gap granted to the application being audited defeats the audit. osy policy audit shows the rules of this kind that apply to your app.
When a rule keeps audit trails a minimum time: audit.retention#
For example: Every audit trail is kept at least 365 days under your organization's policy, whatever app.Audit says.
Declared by platform. Value: days. Mode: range.
An example rule.
audit.retention (range) = at least 365The code it affects: the application's app.Audit settings: a trail's Retention.
Where it binds: the audit purge, run for each application: no trail's rows, the schedule's occurrence log included, are deleted sooner than the rule's minimum, in whole days, whatever the application's app.Audit Retention says, and a trail the application keeps forever is still kept forever. The workflow purge keeps the same minimum: app.Workflow.Retention reaps no finished run, and sweeps no live run's events, sooner than it (WorkflowRetentionPurge.RunAsync). A rule that cannot be read, a version whose rules are missing, or a runtime that cannot ask holds both purges: nothing is deleted. Nothing is refused at deploy.
The short form: none. Nothing is refused under this rule: the platform reads over what the application says.
The builder explanation (what osy prints to a builder):
Every audit trail is kept at least 365 days under your organization's policy, whatever `app.Audit` says.
Set no `Retention` shorter than the minimum, or none: your organization's minimum is kept whatever `app.Audit` says.
More: `osy policy audit`.
This rule allows no exceptions.How to comply: Set no Retention shorter than the minimum, or none: your organization's minimum is kept whatever app.Audit says.
How to ask: you cannot: an audit rule never allows an exception (your organization's policy admin cannot save one), because an audit gap granted to the application being audited defeats the audit. osy policy audit shows the rules of this kind that apply to your app.
When a rule governs a setting: <Package>.<Type>.<Field>#
For example: Osysharp.Privacy.Settings.RetentionDays is locked at 30.
Declared by a package the application composes. Value: setting. Mode: default, lock or range.
An example rule.
Osysharp.Privacy.Settings.RetentionDays (lock) = 30The code it affects: the application's writes of the setting: its seeds, its migrations, its own code.
Where it binds: the read of an [AppSetting] member a package declares, which gives the organization's value under the rule (lock, range, default) of the policy version in force; for a setting stored as rows, every saved write that breaks a lock or a range is refused, whoever makes it, a statement that changes many rows at once and names the setting under a lock or a range is refused before it runs, and a deploy whose migration writes the setting where a lock or a range forbids it is refused before anything is written, on every deploy path. Not yet: values stored before the rule, and rows a deploy only moves to another table, are not changed to fit it (coming).
The short form (the refusal's message):
`Osysharp.Privacy.Settings.RetentionDays` cannot be set to `90`: your organization's policy locks it to `30`. The reason given: "the reason your organization gives".The builder explanation (what osy prints to a builder):
`Osysharp.Privacy.Settings.RetentionDays` is locked at 30.
Write 30, or remove the write at `seeds/settings.osy:4`.
More: `osy policy settings`.
This rule allows no exceptions.How to comply: Write a value the rule allows, or remove the write.
How to ask: a new rule of this kind is hard: it allows no exceptions unless the organization says otherwise. Where it does, the explanation gives the line: osy policy request Osysharp.Privacy.Settings.RetentionDays <value> --why "…". osy policy settings shows the rules of this kind that apply to your app.
See also#
- Where your app may connect — the .egress file — the app's own outbound allow-list and deny-list, inside the organization's
- package.osy — pinning packages, and adding one with
use - ISettingsProvider and [OrgPolicy]: kits announce their settings, and a setting says whether an organisation may govern it — how a package declares a setting an organization may govern
- Asking Claude to run your Osyrin account — the
osyrin-policyskill, which keeps Claude inside the policy