Update to Cloud Environment

Changed files

Choose a file to see its text changes. Binary or large files show metadata only.

SKILL.md →

references/docker.md →

references/networking.md →

references/packages.md →

references/vpn.md →

references/networking.md

− removed · + added

--- before
+++ after
@@ -1,31 +1,107 @@
 # Cloud environment networking
 
-Read `/etc/codex/network-policy.json` in the selected executor. Version 1 records
-startup HTTP policy, proxy addresses, `vpn_configured`, and `tcp_network_access`
-domains/IP ranges. It contains no credentials. The sidecar enforces access;
-editing this file cannot grant access. A missing file or unsupported version
-does not establish permission.
-
-Use `cloud_environment.environment_status` for current HTTP policy and credential
-readiness on the thread's bound environment. It may describe a different executor
-from an extra attached environment. It does not report TCP grants or VPN health.
-HTTP policy can change after startup; null means unspecified.
-Restricted HTTP policy permits listed `egress_rules` hosts; an empty list grants
-no user destinations. Unrestricted policy still has platform protections.
-Credential bindings and platform bootstrap exceptions are separate.
-
-## HTTP/HTTPS through the sidecar
-
-Use the inherited `HTTP_PROXY`/`HTTPS_PROXY`, normally `http://proxy:8080`.
-HTTP destination and credential-injection rules apply. Keep this path for injected
-credentials; a configured proxy placeholder is not an application credential.
-Preserve the inherited proxy settings and configured CA trust, and keep TLS
-verification enabled.
-
-The proxy runs in a sidecar, and the executor has no general Internet route.
-Direct connections, route changes, or unsetting proxy variables cannot grant
-access. An explicit destination-policy denial requires the supported configuration
-workflow; do not bypass the proxy to reach a blocked destination.
+## Network proxy
 
-For configured VPN access or explicit private-network diagnosis, read
-[Tailscale VPN access](vpn.md).
+> **Network requests go through an isolated proxy sidecar.**
+
+Use the supplied `HTTP_PROXY`, `HTTPS_PROXY`, and CA trust settings with TLS
+verification enabled. The proxy routes outbound HTTP/HTTPS traffic, checks
+destinations, and applies configured credentials to matching HTTPS requests.
+HTTPS usually uses TLS inspection with the supplied CA; configured passthrough
+routes preserve end-to-end TLS. Check route compatibility for clients with
+certificate pinning or custom trust stores.
+
+The default agent command runs inside bubblewrap. Its inherited proxy variables
+can point to a loopback bridge that forwards to the managed proxy. In either
+HTTP policy mode, keep the values supplied to the command, including lowercase
+variants and `NO_PROXY`. To test access, run `curl --max-time 20 "$service_url"`
+with the actual destination URL. If a client requires an explicit proxy setting,
+use the inherited value for that protocol.
+
+The sidecar addresses in the policy snapshot are for the outer executor. Only
+an approved agent command running outside bubblewrap can dial them directly.
+If a sandboxed probe resolves `proxy` but reports “Network is unreachable” for
+`proxy:8080`, retry the destination with inherited settings before diagnosing
+an outage or requesting a policy change. Reserve direct probes for questions
+about the sidecar itself. Escalation still leaves Cloud destination policy in force.
+
+The proxy resolves destination hostnames. In restricted environments, local DNS
+lookups can fail while proxied HTTP succeeds; diagnose connectivity with the
+actual proxied request. Supplied `NO_PROXY` settings keep loopback traffic local.
+
+Outbound rules govern services the environment connects to. Incoming access to
+services running in the environment uses the platform's separate preview or
+port-forwarding controls.
+
+## Runtime policy
+
+Use these sources to inspect runtime policy:
+
+- `cloud_environment.environment_status`: environment configuration, capabilities, and observed readiness. Refresh after setup or configuration changes.
+- `/etc/codex/network-policy.json`: startup policy and proxy settings; this snapshot can be stale.
+- `http://proxy:8099/status`: live network policy, VPN settings, and routes. If live status is needed, run this direct probe in the outer executor using an approved escalated command: `curl --noproxy proxy -fsS --max-time 5 http://proxy:8099/status`.
+
+For restricted HTTP access, `network_policy.allowed_hosts` contains custom host
+rules, and `presets` lists enabled host bundles. When present,
+`preset_allowed_hosts` contains resolved preset rules and `effective_allowed_hosts`
+contains the complete desired HTTP allowlist. These fields describe desired
+configuration; require `observations_current: true` and
+`network_policy.state: enforced` before treating it as applied. The local file's
+`http_network_policy.egress_rules` provides the startup expansion.
+
+Exact HTTP host rules cover that hostname across paths, methods, and ports.
+`*.example.com` covers subdomains; include `example.com` for the apex. Include
+redirect destinations such as download, CDN, and authentication hosts.
+
+Both HTTP modes apply platform destination blocks and protect proxy-local
+addresses. Environment registration and initial repository checkout use separate,
+scoped platform access rules.
+
+HTTP policy updates apply to subsequent authorization checks while existing
+tunnels and streams continue. After a user saves changes during onboarding,
+call `cloud_environment.environment_status` again and validate access with a fresh connection.
+
+## Credentials and outbound identities
+
+Use status-reported secret bindings, runtime variable names, and identity aliases
+to plan commands. Keep credential values private and use metadata for diagnosis.
+Use configured SDKs and CLIs normally: the proxy translates credential placeholders
+on matching HTTPS routes. Destination access follows the network policy;
+credentials follow each binding's destination and request scope, including
+scheme, hostname, port, method, and path.
+
+For CLI or SDK profile selection, read the identity metadata manifest at
+`OIC_MANIFEST_PATH` when present. Its version 1 JSON contains a `connections` list.
+Select the entry whose `alias` matches the task's intended identity; `is_default`
+marks the provider's default. Set these variables for that command from the
+selected entry:
+
+| `provider_kind` | Environment variable ← manifest field |
+| --- | --- |
+| `azure` | `IDENTITY_ENDPOINT` ← `identity_endpoint`; `AZURE_CONFIG_DIR` ← `config_dir` |
+| `aws` | `AWS_PROFILE` ← `alias`; `AWS_CONFIG_FILE` ← `config_file` |
+| `gcp` | `CLOUDSDK_CONFIG` ← `config_dir`; `CLOUDSDK_ACTIVE_CONFIG_NAME` ← `configuration_name`; `GOOGLE_APPLICATION_CREDENTIALS` ← `credentials_file` |
+
+Preserve inherited authentication headers, guard variables, and injected
+credentials. Use credential file paths as selectors. Check the entry's `setup`
+outcome when diagnosing CLI failures, and report missing or unsupported manifest
+versions, identities, or selector fields.
+
+## Request failures
+
+Inspect the response body and headers to distinguish proxy limits from remote
+service errors. The proxy applies rate, size, and duration limits. Honor
+`Retry-After` on proxy `429` responses. For `503` responses saying
+`Request size too large` or `Average request size too large`, reduce request size
+or upload rate respectively. Effective limits depend on the configured route.
+
+## Configured VPN access
+
+Read [Tailscale VPN access](vpn.md) when the local policy reports
+`vpn_configured: true` or when explicitly diagnosing VPN or private-network
+access, even if the flag is missing or false. It covers the supported HTTP and
+TCP routes, connection checks, and troubleshooting. When the local snapshot has
+`automatic_tailscale_access: true`, Tailscale destinations need no HTTP or TCP
+grant; HTTP policy governs non-Tailscale connections. Older environments use
+the separate `tcp_network_access` domain and IP-range grants. Raw TCP always
+uses application-supplied authentication.