Skip to content

Custom network policy ​

Agents run inside an OpenShell sandbox that restricts outbound network access. If a package install or build step fails because the sandbox blocks a host your project needs, create a custom policy that adds the missing endpoints.

How the sandbox policy works ​

The policy controls two things:

  • Endpoints -- which hosts and ports a process can connect to.
  • Binaries -- which executables are allowed to use each endpoint.

A request is allowed only when both the destination host and the calling binary match an entry in the policy. Even if a host is in the allowlist, only the listed binaries can reach it. curl is excluded from GitHub-forge profiles to prevent raw HTTP access with injected credentials. The GitLab and Jira forge profiles allow curl because their API access requires it (the gh CLI is not available for GitLab or Jira).

All agents share the base policy policies/base.yaml. Forge-specific network access (GitHub, GitLab, Jira endpoints) is provided by profiles under profiles/ and wired in via forge-level or overlay sections in each harness file. See the individual profile files for the full list of allowed hosts and binaries.

Before you start ​

  • You have a custom harness (.fullsend/<agent>.yaml) in your repository for the agent you want to configure. If you do not have one yet, see Customizing agents for how to create one.
  • You know which host is being blocked. Check the agent logs for ECONNREFUSED, ETIMEDOUT, npm ERR! network, or similar connection errors that name the blocked hostname.

Add custom endpoints to the policy ​

1. Create a policy file ​

Copy the default policy for the agent you are configuring (for example, policies/base.yaml for the code agent) to .fullsend/policies/<agent>.yaml in your repository and append a block for the host you need:

yaml
network_policies:
  # ... existing policies from the base file ...
  your_policy:
    name: custom-hosts
    endpoints:
      - host: "example.com"
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: "**/node"
      - path: "**/npm"

Use access: read-only unless the endpoint requires write access.

Some URLs contain encoded slashes (%2F). If the endpoint you are adding uses them (common with Go module proxies and some GitHub download paths), add allow_encoded_slash: true to the endpoint entry. See the OpenShell policy schema reference for the full list of available fields.

2. Reference the policy in your harness ​

Add the policy: field to .fullsend/<agent>.yaml:

yaml
# .fullsend/<agent>.yaml
base: https://raw.githubusercontent.com/fullsend-ai/agents/<SHA>/harness/<agent>.yaml#sha256=<sha256sum>
policy: policies/<agent>.yaml

If you already have a custom harness (for example, with a custom sandbox image), add the policy: field alongside the existing fields.

3. Test the policy ​

Trigger the agent again and check the logs for new connection errors. Policy changes often need a few rounds of iteration -- the first blocked host you fix may reveal a second one behind it (for example, a registry that redirects to a CDN). Repeat steps 1 and 2 until the agent run succeeds.

4. Repeat for other agents ​

All agents share policies/base.yaml with forge-specific network access provided by profiles. If multiple agents need the same custom hosts, create a separate override for each one. For example, the code and fix agents both use policies/base.yaml (GitLab network access is provided by forge-level profiles such as fullsend-gitlab-code and fullsend-gitlab-ro).

Troubleshooting ​

When a package install fails due to a blocked host, look for connection errors in the agent logs:

SymptomCause
ECONNREFUSED or ETIMEDOUT on a hostnameHost is not in the policy
npm ERR! network followed by a hostnamenpm cannot reach the registry or download URL
pip or go get failure referencing an external URLDownload host is not in the policy

To identify which host to add:

  1. Find the failing command in the agent log output.
  2. Look for the hostname in the error message (for example, codeload.github.com).
  3. Add the host to your custom policy under an appropriate network_policies entry with the binaries that need access.

See also ​