Skip to main content

Where a task may send bytes

This page covers the egress decision: which tasks are limited to hosts their owner approved, what enforces it, and what stays open on purpose. The rules for owners are in Scheduling.

What it does and does not close​

A task that can read private data and also fetch an arbitrary URL can be made to leak that data in the URL. Any reachable host can receive data in a path, a query string, a subdomain lookup, a redirect chain or a search term. The audit's finding H-2 names this, and the general case cannot be closed while a task has both open browsing and private data.

H-2 is closed for an unattended task on its job's own terms. It is not closed for an attended turn. A person asking in chat still gets open web with their private data in reach, and a page that turn reads can still make it send that data somewhere. That is accepted, because the person is present and open browsing is the point. tests/test_egress_closure.py::TestTheAcceptedRisk shows the canary reaching the attacker's host on both brains, so the risk stays a tested statement.

The decision​

rooms.scopes.reach_for_task computes one answer per task, from the root of the parent_task_id walk, so a subtask or !retry copy gets its root's answer. Reach.egress_hosts is None for any public host, or the exact set of hosts approved.

The taskegress_hosts
A guest's or correspondent's turnNone. web_tools_load decides whether it has web tools at all
An attended own turn (Talk, web, email, SMS, WhatsApp, REPL, CLI)None
Briefing or shared block researchNone. It holds nothing private
A job with an approved open: for its current textNone
An occurrence [security] scheduled_job_max_unapproved gave full, and any subtask of itNone
A job with an approved public: for its current text, whose row asks for public, or an occurrence the setting gave publicNone. It holds nothing private
Any other scheduled job or assignment wakeThe hosts in its grants
A personal briefing, or a TASKS.md line, its subtasks and !retry copiesThe empty set, with no skills
Any other unattended source type, a read failure, no databaseThe empty set

TASKS.md counts as unattended because a limited task can write a line into it, so a line cannot be reviewed as a job's text can. A line that needs the web fails with an ordinary refusal in its result. A personal briefing's model has no tools, since the daemon gathers its sources before the model starts (Briefings).

Grants and subjects​

A row in egress_grants means approved, and there is no pending or denied state. A grant hangs on a subject: cron:<job name> or assignment:<id>. A personal briefing and a TASKS.md line have no subject, so nothing can be granted to them and their refusals are not recorded. Settings, Scheduled jobs and Settings, Assignments are where an owner decides; the routes for it stay under /settings/network, with no listing of their own, since each page reads a subject from its own listing. db._migrate_egress_retire_subjects deletes the rows the earlier briefing:<name> and tasks-file subjects held and closes their open bell rows.

EntryMeaning
<host>That exact host at 443, for WebFetch and the shell. No subdomain, scheme, path, wildcard or IP literal. <host>:443 is the same entry
<host>:<port>That exact endpoint, for the shell only, if the operator allows it (below). An IP literal goes here, with IPv6 in brackets
skill:<name>One external skill. skill:browse runs on the isolated profile with no credential verbs
public:<digest>This exact job text runs with no private data and open web
open:<digest>This exact job text runs as it did before, with the user's browser profile and every skill

The digest covers a job's prompt, command, skill, skill_args, publish_shared_kv and publish_shared_kv_trusted. The last two are there because a job's answer goes where they say, into other users' briefings. The sync resolves prompt_file into prompt, so the file's content is covered. Editing any of them drops the job's open: and public: approvals and asks again, unless the setting below covers the job. A schedule, model or delivery edit does not.

The re-ask explains itself. When the job's row names the digest a dropped grant named, the sync keeps that text and the grant's time on the egress_refused row (approved_text, approved_at), and each later edit moves only text_changed_at, so the diff on the job's page always runs from the text the grant named, and a harmless edit cannot hide a later one. A grant the upgrade seeded says it was carried over rather than approved (approved_via), since nobody read that text. A grant naming other text records nothing, and that request reads as a plain ask. The diff splits on \n alone, so text whose digest moved cannot read as no change, and it spells out what a browser would not draw (\u{200b}), because a model reads a zero-width or tag character and the owner would not see it. The Access control's dialog shows the full text as it is and does not do this. Lookalike letters show as ordinary changed lines. Past 100,000 characters or 2,000 lines the page says it is too long to compare and offers only the Access control, whose dialog shows the whole text. The page's one-click approval is POST /settings/network/access with the digest from the same read as the diff, so a later edit gets stale_job. Approving, dismissing or removing the job ends the record. The bell's text stays fixed; the explanation is on the page it links to, since the text is model-writable and a push can reach a shared room.

An endpoint grant can reach a private address or a port other than 443, so it needs both sides. The owner's grant says which job, and the operator has to allow the endpoint already, in one of three ways: [security.network] extra_hosts, which names that exact endpoint and also opens it to every task; an egress grant in [private_hosts], which covers any port on that host and opens nothing until a job is granted it; or, for an admin's own jobs, a credential the admin added and bound to that endpoint. A credential a task made with istota-credential new does not count, because the model chose its URL. Nor does an accepted share's, whose URL the sender chose, or a non-admin's, because any user can add one. No other consumer's grant in [private_hosts] counts. egress.operator_endpoints is that rule. add_grant refuses an endpoint the operator does not allow, and executor._egress_grants_in_force checks again for each task, so withdrawing the operator's side withdraws what was granted on it. A plain name in that table or in extra_hosts may resolve to a private address too. A credential binding lets only a literal address be private: a bound name must still resolve public, because listing a name switches off the proxy's address check and its DNS would then decide where the daemon connects. An entry cannot state a loopback, link-local, multicast, unspecified or reserved address, because the proxy connects from the daemon's network. A name the operator wrote is checked by nothing further, as it always has been. A binding adds nothing by itself: the grant is what puts an endpoint on the list. CRON.md's egress drops and reports an endpoint the deployment does not allow, so a once job does not wait on a button that refuses.

Only an authenticated person writes a grant: the web route for the signed-in user's own subjects, the operator's istota egress, and the one-time seed. tests/test_egress_grants.py holds that list, and no skill CLI or deferred handler imports the module. An approval over the web carries the digest of the text the page showed, and a row that has moved since is refused. An approval also binds the task: an occurrence whose prompt, command, skill or skill_args differ from its job row runs limited, so a task queued before an edit does not run on the edited row's approval.

Asking ahead​

A job's egress in CRON.md lists hosts and skill: entries. The sync stores it in scheduled_jobs.egress_request and files each entry with no grant and no row in egress_refused, which is the one list the owner answers and the bell reads. So a declaration is the same kind of thing as a refusal: it grants nothing, and the file is model-writable. It is outside the digest, because it widens nothing. A skill the owner could not approve is dropped at parse, along with open: and public:, and no log line names an entry.

A once job with an unmet declaration, or a reach the setting does not cover, holds its fire in check_scheduled_jobs. The hold comes ahead of the staleness check and such a job is exempt from that check, since an approval can take days and a fire skipped as stale would spend its only slot. A manual run is refused while the job waits, in run_scheduled_job_now, which is the path behind istota job run, !retry, the bell and the job's Run now in Settings. That refusal also covers a disabled or suspended once job, which the page does not show as waiting because nothing is firing it: a successful run would still delete it. The hold is read from the grants and not from the rows, so a dismissal does not release the job and the page keeps naming what it waits for. A once job that declared nothing still fires limited and takes its refusal rows with it when it deletes itself. An occurrence deletes its job only if it ran the text the row and the file still hold: the completion path compares tasks with the row, and cron_loader.remove_finished_once_job compares the file under its lock, since an edit may not have reached the row. An edit kept this way goes through the sync's edit path, so its approval is dropped and the job holds again, and the sync clears last_run_at so that a dated job is not left a year from its next slot.

The deployment default​

A job's reach says what it runs as: limited, public or full. private is the earlier spelling of limited, and a job that states nothing is limited. [security] scheduled_job_max_unapproved is the widest a job gets with no approval, public by default. A typo reads as limited, and the config editor asks for a typed confirmation.

SettingA job stating nothing or limitedpublicfull
limitedLimitedLimited, asksLimited, asks
publicLimitedPublicLimited, asks
fullFull, or limited if it says limitedPublicFull

The job page's Access control is one route, POST /settings/network/access, over egress.set_job_access and cron_loader.update_job_reach_in_cron_md. The file is written with no database transaction open. A wider choice writes it first and refuses if it cannot, and a crash or a moved text after that leaves a reach with no approval, which grants nothing the file could not already ask for. Limited takes the approvals off first and leaves a file alone unless what it says would run as more or keep asking, so an unwritable file cannot hold a job on full access. The writer refuses a document with an entry it could not read, since the rewrite is built from the jobs that parsed and would delete the rest. A choice the setting covers stores no approval, so editing its text raises nothing to answer.

egress.unapproved_reach holds that table. Asking for less is never worse off. A job stating nothing stays limited under public so that one needing memory does not run without it and give a worse answer with no error. It runs on full under full because that is what the operator asked for.

The answer is on the occurrence. _create_scheduled_job_task writes tasks.egress_unapproved, so a config change moves nothing already queued, and it covers no other source type. An approval still counts under every setting, so a job with open: approved and reach = "public" runs on Full access, as the page says. An occurrence the setting let run publishes its answer untrusted, whatever publish_shared_kv_trusted says: nobody read the flag, and a page can write the answer. Removing an approval leaves a dismissed request, so a job whose file still asks does not ask again.

public is the default because a page a public job reads has nothing private to steal. Its residual is the job's own text, which no person reads under this setting: a limited task can put what it holds into a job's prompt, and the job can send that anywhere. full reopens H-2 for scheduled jobs: each occurrence runs as an approved open: does, with the user's browser profile, every skill, no verb rules and unheld mail, so instructions a job reads can send what it holds to any public host. istota doctor warns under security.egress_open_jobs while it is full.

What enforces it​

ChannelLimited taskOpen task
WebFetch, native brainWebFetchPolicy.exact_hosts, checked on every redirect hop before anything resolvesPublic addresses
WebFetch, CLI brainsThe same policy, in the document istota_web readsPublic addresses
Shell, git, pip, npm, cron command: jobsextra_hosts, the Nextcloud host, each plain grant at 443 and each endpoint grant the operator allows. Registries and forges only if grantedThe skill-keyed allowlist
WebSearchUnchangedUnchanged
BrowserWithheld without skill:browse. With it, the isolated profileThe user's profile
Devbox and other external skillsWithheld without a skill: grant. developer stays, and without skill:devbox it has no exec socket, so a shimmed npm or node exits 120Available
feeds add, feeds import-opml, bookmarks add, ntfy --topicRefused, egress_limitedAvailable
briefings sources add, sources set, blocks add, blocks saveRefused. The daemon fetches what they nameAvailable
briefings_config shared-block set, set-prompt, run, remove, group save, group setRefused. Research runs with open web on what they writeAvailable
MailAnything but the user's own addresses is held as a draft. Mail naming the bot's address is refusedThe user's own policy
room postNo private origin, so refusedAvailable

A heartbeat shell-command has no task row and no subject. It reaches operator hosts only.

Refusals and the bell​

Each seam appends {"channel", "entry"} to egress-refused.jsonl in the task's control directory, and the executor reads it when the task ends. A refused task is told where it can be answered, by lib/egress_log.refusal_advice: the page of its subject's kind, or that nothing can be approved for a task with no subject. A refused hostname can carry data, so it stays in the framework database, only its owner reads it, no log line names it, and it is never pushed. The channel decides what a line may become, so https://open/ cannot read as a request for full access.

The bell has one row per subject with fixed text. Its detail names the subject and no host, and its one action opens the job's or the assignment's own page, through a redirect whose path carries only the row's integer. There is no Allow in the bell, because a hostile page chooses the hostname.

A verb refusal logs nothing, since no grant could allow a verb.

Public jobs​

A public job is the research posture applied to one job, approved or allowed by the setting. It keeps its user identity, its room and its delivery target. It has browse, skills and untrusted_input, and loses everything else.

  • It has no memory, no files, no vault and no conversation context, and its prompt names none of the user's email addresses. Its prompt keeps the user id and the user's timezone.
  • It has no notes of its own in its room. Channels/<token> is not bound and CHANNEL.md is not loaded, because in a private room that file is the user's notes.
  • Its deferred files are purged except subtasks, because the directory is writable by a model reading strangers' pages.
  • A subtask of a public job is public too, and so is a !retry copy.
  • The posture is on the task row. tasks.egress_posture is written once by the daemon before the model runs, as public or private, and the drain and descendants read that rather than the job row, which a once job has lost by then and an edit can change in flight. An occurrence nobody decided whose job has gone drops its deferred files, and its descendants withhold every scope. A job re-run is a new occurrence and decides from the job as it stands.
  • It needs the sandbox, the network proxy, the skill proxy and the browser. A missing one fails the job with the same reason research gives, so a job's last error can read briefing_research_network_proxy_unavailable.

Deliberate open paths​

Each of these is known and left open.

  • Attended turns. As above: H-2 stays open for them.
  • The worktree reaper's fetch. The daemon runs git fetch origin only when the origin is a configured forge, read through the repository's own insteadOf and refused with a proxy in its config. A limited admin task can still point it at a path on that forge, and the repository's http.* config still applies; what that sends goes to the forge.
  • HEARTBEAT.md url-health. HEARTBEAT.md is writable by a task, so a limited admin task can plant a check, and it runs from the daemon's network on the next sweep. The check and every redirect hop reach only a host with a heartbeat grant in [private_hosts]. What remains: the task can read a status code from a granted host and send it a path and query, a grant covers every port and scheme on the host, and a granted shared platform also serves other people's accounts.
  • Delayed egress. A limited task can write text into memory or a file, and a later attended turn can read it and act on it. A public job's answer is delivered, and may be indexed where a job's output is.
  • scheduled_job_max_unapproved. Under the default public, a limited task can write a public job and put what it holds into its text, which then goes to any host with no person reading it. Attended turns gain nothing from this, since they have open web already. Under full a limited task can write a job that has everything an approved open: gives on its next run, an escalation out of limited, and istota doctor warns. limited closes both.
  • Jobs on open. Every job that existed at upgrade starts on open and keeps this risk until its owner narrows it. istota doctor counts them under security.egress_open_jobs, and warns only for those that run: a disabled or suspended job is a note, since its approval applies again once it starts.
  • What an open job reads. The digest does not cover a workspace file the job follows or a script it runs. Anyone who can edit that file can steer a job with full access, a limited task included.
  • WebSearch. The query reaches the search provider. That is a deliberate disclosure: the provider is not a recipient an attacker can read.
  • Fixed-provider lookups. markets and yfinance lookups carry what the model puts in a symbol to a fixed provider, the same standing as WebSearch.
  • Shared platforms. Granting github.com or pypi.org grants a host that also serves attacker accounts. Grants are per host, not per tenant, and the job's page says so.
  • The browser and the devbox once granted. skill:browse and skill:devbox are unbounded for that job. A leak cannot be stopped per URL in a browser, since redirects, clicks and forms all send data.
  • No sandbox or network proxy. WebFetch and the skill gates still apply, and shell egress is then unbounded. With skill_proxy_enabled = false nothing sets ISTOTA_EGRESS_LIMITED, so the verb rules do not apply.
  • Skill CLIs run host-side. The CONNECT list does not bound them. A local skill is local because the model cannot pick its destination beyond the verb rules, and that survey is not a proof.
  • Mail with a person in the loop. A held draft may carry private data out once a person approves it. An own address that forwards into the bot's mailbox passes the gate, since Istota cannot see the forward. --reply-to the bot on mail to an own address is not refused, since returning needs the person to reply.
  • ntfy --click and links in mail to the user. A URL the model wrote reaches the user's own device and leaves only if they tap it.
  • Credentials a limited task keeps. A limited task keeps its vault and grants. A placeholder can go only to an approved host, and istota-credential get for an entry marked readable returns the value into the task, where it can leave only by an approved host or an open verb.
  • Writers left open on briefings_config. group run (with --mode publish), group delete, group delivery, group revoke-approval, schedule set and schedule remove change no prompt or source and stay open under the flag. group run can start research on a definition its owner already wrote.
  • Pollers. An already-subscribed feed's poller, feeds refresh and poll keep fetching. A limited task cannot change what they fetch.
  • A limited job's publish target. A job needs no approval to run limited, so a limited admin task can plant a job whose publish_shared_kv sends its answer, written with memory in reach, to shared KV. That reaches other users' briefings and leaves no host. _publish_result_to_shared_kv gates on the writer and reads no reach, and it does not check for a reserved namespace.
  • CRON.md target. A planted job's target can name a room. A shared room is refused. Whether another user's private room is refused was not established in this work.

Residuals​

  • The isolated profile is shared. A job that signs in by typing with --fill or --type leaves that session in the profile every isolated task uses. Credential verbs are refused there, and typing cannot be.
  • Browser capacity. All isolated tasks hold one of two Chrome slots. With two users holding live tabs the isolated profile gets a 503 until a tab passes its ten-minute lifetime, and a kept isolated tab holds a slot against a third user. At four tabs in all, a new owner's tab replaces the oldest anywhere. Tasks take turns on the display and do not run in parallel. Capacity was measured with Chrome stubbed, so there are no memory or latency figures.
  • Other browser identities. Shared blocks browse under __system__, a profile of its own. An own turn in an incognito room keeps the user's profile. istota user ensure __isolated__ is not refused, though the row is inert.
  • A flood of refusals. A task can fill the log's 64 KiB cap with chosen names and the table keeps 20 rows per subject, so a real host can be pushed out. A request about the job survives eviction.
  • Ports. A CONNECT to a granted host on another port is refused and logged as that host, with no port, so the page's Add button offers the name at 443. An owner types host:port to grant the endpoint. A refused IP literal is not offered at all.
  • Plain HTTP. The proxy forwards plain HTTP only through the credential broker, so an endpoint served over HTTP also needs a credential bound to http://<host>:<port> with HTTP allowed on its grant. A grant from [private_hosts] alone reaches a TLS service.
  • A grant the operator stopped allowing. It stays on the job's page while the task is refused. The log counts these and names no host.
  • An operator's skill override. An override of a bundled skill with no egress loads as external. For a skill with exclude_memory that withholds it on a limited task and its exclusion no longer applies, so an override of briefing with no field loads dated memories into a limited briefing's prompt.
  • No database. reach_for_task with no database answers the empty set, even for an attended task.
  • A renamed job starts from nothing. The old name's rows go and the new name has no approvals.
  • A module job's stale rows. The seed covers _module.* rows too, where they do nothing, and the module sync's prefix delete leaves them behind. Doctor does not count them and Settings, Scheduled jobs hides them.
  • Skill jobs. A cron skill: job has no proxy, so its reach is read with no own_addresses, and a public skill: job's environment holds the index's declared credentials, as every skill job's does. It can run only browse, skills or untrusted_input, with arguments its owner approved by digest.

What verifies this​

The default suite drives real proxies and real CLIs on the host and checks argv, so it has not executed the sandbox path. scripts/test-linux.sh runs the namespace, uv run pytest -m image -n0 the browser container, and scripts/test-upgrade.sh the seed migration over an older release. uv run pytest -m smoke -n0 runs two more through the shipped scheduler: tests/smoke/test_public_job_in_stack.py is an approved public job and its subtask, with no browser container started, and tests/smoke/test_limited_mail_account.py is a limited job's mail from a connected account, read from a real mail server. Neither brings up a room, so CHANNEL.md staying out of a public job has no witness in a stack.