CodeHerderSearch⌘KRequest access →

Network access approvals

How a session asks for a blocked network destination, who can answer, what each answer allows, and how to revoke it.

When a session needs a network destination that its policy blocks, it can ask a person. A failed system image build can ask too. This page explains what you see, what each answer does, and how to manage the answers later.

A network request is not a question. It has no free-text answer. You approve one exact destination, or you deny it.

Which sessions this applies to

Session requests apply only to sessions whose network is enforced. An enforced session runs in a container, and its stage connects through its own proxy. See Isolating agent runs on a device.

A session that runs without that proxy is not enforced. Its Network access panel says “This session’s network is not enforced. Approvals here do not limit what it can reach.” A request for such a session is refused.

A system image build has no session. See Requests from a system image build.

Where requests appear

  • Dashboard. The “Network access approvals” panel lists pending requests. Each row offers every answer you may give. The attention badge in the sidebar counts them together with open questions.
  • Needs you. On My work, a request for your own task appears when you are an admin of its workspace, or when Show team is on.
  • Settings. The Requests list shows requests for the workspace.
  • Slack. A request from a failed system image build can post to a Slack channel. Add a route with the “Network access requests” category. See Slack.
  • Session page. The Network access panel shows the policy of that session. A separate “Network access requests” panel lists its requests. A task-free session has both panels.
  • Task page. The “Network access requests” panel keeps the history after the session ends.

One request for each destination

Lists that cover the whole workspace show one pending request for each exact target. This applies to the Dashboard and the Requests list in Settings. In the Requests list, the request card shows “Asked by” and the number of sessions when more than one session asks for the same target. The Dashboard row does not show this count. The badge also counts one for each target.

The Session and Task pages still list every request of that session or task. A build request is not tied to a session or task. It shows on the Dashboard and the Requests list.

Some answers reach the other sessions that wait for the same target:

  • Deny closes them all as denied. Each of those sessions then waits 24 hours before it can file an automatic request for that target again.
  • Always allow in this workspace closes them all, because the new rule covers them.
  • Allow for this session closes only the request you answered.

A new workspace rule added in Settings also closes the pending requests for its target.

What a request shows

  • The exact host, the port and the transport. The transport is “HTTPS tunnel (CONNECT)” or “HTTP”. A request never holds a URL.
  • Requested by, Session, Task and Device. A request with no task or device shows a dash.
  • Blocked because. The reason the destination was blocked.
  • Origin. “Raised by the proxy” or “Asked by the agent”.
  • Reason given by the agent (unverified). The agent wrote this text. Treat it with care.
  • Seen. How often the proxy saw the connection, and when it last did.
  • Expires. Shown on a pending request. A request that nobody decides within 24 hours expires.

A request has one status: Pending, Denied, “Allowed for this session”, “Allowed in this workspace” or Expired.

A target is exact: one host, one port and one transport. A rule for github.com does not cover api.github.com. A target never uses a wildcard, an IP address or a URL.

Only two reasons can be approved: “Host not on the allow list” and “Port not approved”. Other reasons cannot be approved. Examples are “Always blocked”, “Reserved address”, “Blocked by the operator”, “Restricted by session purpose” and “Blocked by a workspace rule”. The buttons then explain: “A protected rule blocks this target. No approval can lift it.”

The three answers

These answers apply to a session request. A build request has two; see Requests from a system image build.

Only a human workspace admin or owner can answer. An agent can never answer, and a session credential cannot either.

  • Deny. The destination stays blocked. The same session cannot file an automatic request for that exact target for 24 hours.
  • Allow for this session. The destination opens for this one session. A package manager can open many connections, and all of them are allowed. The access ends when the session ends, when you revoke it, or after 12 hours.
  • Always allow in this workspace. CodeHerder saves an exact rule. Current and later sessions in this workspace can reach this destination until you revoke the rule. This answer asks you to confirm first. If the session has ended, the dialog says that the rule applies to later sessions only.

A denied or expired request can still be allowed later. Deny is not offered then, because the request is already closed. An allow after the fact also lifts the 24-hour wait on automatic requests for that session and target. Other sessions that the same Deny closed still wait.

If the session has ended, Allow for this session is disabled. The reason reads “The session has ended. Allow this target for the workspace instead.”

If you cannot decide, a request card says “Ask an admin to decide” and names who can. An Ask admins button emails the workspace admins once. The card then shows “Admins asked” with the time.

Requests from a system image build

A workspace can declare system packages or a Dockerfile fragment. A device then builds a system image for it. See Giving stages the tools they need. During that build, the network reaches only a short default list of hosts. If the build needs another host, the build fails. CodeHerder then files one pending request for each blocked target, up to 16 for one failed build. The request belongs to the workspace, not to a session or task.

A build request looks like a session request, with these differences:

  • Requested by reads “System image build”.
  • A Build row shows the device name and a short image hash. The card has no Session row, and Task shows a dash.
  • It follows the same rules for approvable reasons, exact targets, automatic requests and expiry. A repeat from a later failed build adds to the same pending request.

Two answers work:

  • Always allow in this workspace. CodeHerder saves a build rule. The confirm dialog says: “The rule applies to this workspace’s system image builds only. The system image rebuilds.” The device builds a new image with the host open. You do not start a rebuild.
  • Deny. The workspace files no automatic build request for that target for 24 hours.

Allow for this session is disabled. The reason reads “A system image build has no session. Allow this target for the workspace instead.”

Build rules and session rules are separate. A build rule never opens a host to an agent session. A workspace rule never opens a host to a build. To let both use a host, save one rule of each kind.

A rule belongs to one workspace. A group does not pass build rules down. See When a build needs another host. For a worked example, see PHP and Composer in container stages.

A device needs a current ch to build an image that uses build rules. An operator can also turn this off for a device. Such a device does not build that image.

After you decide

CodeHerder saves your decision first. The session’s proxy applies it a moment later. The request shows one state:

  • Applying. “Saved. Waiting for the session’s proxy to apply it.”
  • Applied. The proxy applied the decision. The destination is open.
  • Device offline. “Saved. The device is offline. Added access stays closed until it reconnects.” Deny rules stay in force.
  • Not supported or Failed. The proxy cannot apply the decision. The request shows the reason.
  • Session ended. “Saved for later sessions. The requesting session has ended.”

After the proxy applies an allow, CodeHerder tells the session to retry. It never replays the connection for the session. A session that muted this notice gets no advice and must retry on its own.

Workspace rules, allowances and settings

Open Settings, then Network access. The sections appear in this order:

  • Automatic requests. When on, a blocked connection files a request by itself. This is the default. When off, enforcement does not change, and agents can still ask on purpose. Automatic requests also need a device that reports blocked connections. Otherwise the session shows “The device needs an update to report blocked connections.”
  • Policy status. How far the saved policy has reached the sessions running now.
  • Inherited policy. The read-only defaults every session starts with.
  • Workspace rules. Exact targets saved for every session. They do not apply to system image builds. Choose New rule and fill in Host, Port, Transport and Effect. Choose Allow or Deny. A deny rule beats an allow rule and an open network. A rule with the opposite effect of an active rule for the same target conflicts. To remove a rule, choose Revoke. Turn on Revoked rules to see revoked rules as history.
  • Image build hosts. Exact targets saved for this workspace’s system image builds. Choose New build rule and fill in the target and Allow or Deny. A row says “Saved from a request” or “Added here”. To remove a rule, choose Revoke. Adding or revoking a rule rebuilds the workspace system image. The Revoked rules toggle in Workspace rules also covers this list.
  • Session allowances. Allowances for one session. Revoke one to end it at once.
  • Requests. Every request stays visible after the session ends. Use Request status to narrow the list.

A person who is not an admin sees a read-only view. It says “Read-only view. Changing network access requires a workspace owner or admin.”

Limits

Each session can file 5 new requests a minute. It can hold 20 pending automatic requests. System image builds share the same limits for each workspace. Past a limit, the app shows “Some blocked connections were not filed”. The destination can ask again after the limit passes.

From the command line

Triage pending requests, then decide:

ch egress list --status pending
ch egress show <requestId>
ch egress approve <requestId> --scope session
ch egress deny <requestId>

ch egress approve also allows a denied or expired request after the fact. ch egress deny works only on a pending request.

ch egress approve has no default scope. Choose session or workspace. Add --yes when you do not run it at a terminal.

List and create build requests and rules with --purpose build. The list commands show both purposes by default. A new rule has the stage purpose unless you add --purpose build:

ch egress list --purpose build --status pending
ch egress rules list --purpose build
ch egress rules create packages.sury.org:443 --effect allow --purpose build --yes

ch egress approve <requestId> --scope session is refused for a build request. Use --scope workspace.

An agent or a person can file a request. A person names the session:

ch egress request registry.npmjs.org:443 --reason "install the lockfile deps"
ch egress request example.com:80 --transport http --session <sessionId>

The reason holds 500 characters at most. A URL is refused.

Read policy, rules and allowances, and manage them:

ch egress policy <sessionId>
ch egress rules list --all
ch egress rules create blocked.example:443 --effect deny --yes
ch egress rules revoke <ruleId> --yes
ch egress grants list --session <sessionId>
ch egress grants revoke <grantId> --yes
ch egress settings show
ch egress settings edit --auto-request off

See Using the CLI for sign-in and output options.

When a task waits for a decision

A denial never stops a task by itself. The agent keeps going. When it needs several destinations, it asks for all of them first and then blocks the task once:

ch egress request registry.npmjs.org:443 --reason "install the lockfile deps"
ch egress request pkg.example:443
ch task block --on-egress <requestId>[,<requestId>...]

ch task block --on-egress <requestId>[,<requestId>...] blocks the task on every listed request. A second block adds to the blocker the task already has. The task page shows “Waiting for network access approval: host:port” for each destination, with a link to this page. You can’t resolve this blocker by hand while a request is pending. ch task unblock refuses it. Allow or deny each request instead.

The task starts again after every listed request is decided or has expired. You can decide them together: the approval list names the tasks that wait on each target. The new session reads each destination with its outcome:

  • Allowed for the workspace: the agent retries it.
  • Denied: the agent does not work around it. It continues without the destination, or asks you.
  • Expired: the agent asks you to decide.

Blocking a task ends its session, so a session-only allowance cannot help it. Allow a blocked task’s destination for the workspace, or deny it. A session-only allowance is no longer offered once the session ended.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close