Skip to Content
ConceptsNetwork policy

Network policy

Decide exactly which internet addresses your agents can reach. Every outbound call from a space passes through Marshal and is checked against an ordered list of rules. Anything the rules do not allow is blocked and recorded, so an agent cannot quietly send your code somewhere new or download from a source you never approved.

What you can do with it

  • Unblock a new dependency in seconds. The agent runs pip install and the request to files.pythonhosted.org is blocked. The space page shows a banner. Click Approve, the install succeeds on the next try, and the approval is recorded in the audit log.
  • Make it stick for next time. Choose Approve & remember for next run instead. The address goes into your manifest’s allow list, so every new space from that manifest can reach it.
  • Lock a stack down. An admin attaches a strict policy to the production stack, with deny rules for paste sites and self-service additions turned off. Every manifest on that stack inherits it.

See it end to end: Let agents use secrets they never see.

How it fits

  • A network policy is a named set of rules plus a Default action, allow or deny. Admins and owners manage policies on the Network policies page. Members can see them.
  • Each organization has a built-in default policy that denies by default. Every new stack gets it automatically. Admins can edit its rules, but cannot delete it. They can also create other policies and attach one to any stack.
  • Each package declares the hosts its tools need, and Marshal allows them for every space that includes the package. Some packages exist only to allow addresses, such as egress-vscode for VS Code Remote-SSH.
  • Each manifest has its own allow list, for addresses you chose to allow in your spaces.

How a request is checked

Marshal builds one ordered rule list for each space when it starts. The first rule that matches the request decides. If no rule matches, the policy’s default action decides.

An allow can come from the stack’s policy, a package or your allow list. A blocked request shows in a banner on the space page, with Approve and Approve & remember for next run.

The order is:

  1. Deny rules from the stack’s policy. An admin’s deny always comes first. No package and no allow list can reopen a host the policy denies.
  2. Allow rules from the stack’s policy.
  3. Hosts that packages declare, including the database hosts of database packages.
  4. Your manifest’s allow list.
  5. The default action of the stack’s policy, for everything else. A stack without a policy denies everything else.

Writing a host pattern

A rule matches the hostname only, with no path or port. * matches any characters, dots included, so *.example.com covers every subdomain of example.com, however deep. Write example.com as its own entry to allow the bare domain too. A git@ or ssh:// prefix asks for SSH to that host.

Wherever Marshal shows a pattern, in a policy, a manifest’s allow list or a package’s hosts, it marks one that does not do what it reads like and suggests the right form:

  • Matches more than it looks like (amber): *example.com also matches evilexample.com, which anyone can register. Write *.example.com and example.com instead. A bare * allows every host.
  • Matches nothing (grey): a leading dot such as .example.com, a path, a port or a user name in the pattern. The entry is listed but allows no traffic.

The marks are advice. Saving always goes through, so a policy you rely on keeps working while you tidy it.

When something is blocked

The banner on the space page lists each blocked address:

  • Approve allows the address in this space right away. It lasts for the life of the space, through stop and resume. New spaces do not get it.
  • Approve & remember for next run does the same, and also saves the address to your manifest’s allow list. Future spaces from that manifest can reach it, behind the stack’s deny rules.

A policy can permit or forbid self-service additions. When it forbids them, Approve & remember for next run and new entries in a manifest’s allow list are refused. An admin adds the address to the policy instead.

Think before you approve. A remembered address applies to every new space from that manifest. Blocked tools and database commands have their own approval prompts in the same banner.

Owners, teams and scopeHome and notifications