> ## Documentation Index
> Fetch the complete documentation index at: https://isol8.notdhruv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Code URLs

> Fetch and execute source code from URLs with SSRF controls, hash verification, and strict policy configuration.

isol8 supports fetching source code from remote URLs before execution. This is useful for GitHub-hosted scripts, Gists, and pinned CI inputs.

## Overview

Remote code execution via URL is controlled by:

1. **Request fields** (`codeUrl`, `codeHash`, `allowInsecureCodeUrl`)
2. **CLI flags** (`--url`, `--github`, `--gist`, `--hash`, `--allow-insecure-code-url`)
3. **Policy config** (`remoteCode` in `isol8.config.json`)

<Warning>
  `code` and `codeUrl` are mutually exclusive. Use one or the other per execution request.
</Warning>

## Enable In Config

Remote URL fetching is disabled by default. Enable it in `isol8.config.json`:

```json theme={null}
{
  "$schema": "./schema/isol8.config.schema.json",
  "remoteCode": {
    "enabled": true,
    "allowedSchemes": ["https"],
    "allowedHosts": ["^raw\\.githubusercontent\\.com$", "^gist\\.githubusercontent\\.com$"],
    "blockedHosts": [
      "^localhost$",
      "^127(?:\\.[0-9]{1,3}){3}$",
      "^10(?:\\.[0-9]{1,3}){3}$",
      "^172\\.(?:1[6-9]|2[0-9]|3[0-1])(?:\\.[0-9]{1,3}){2}$",
      "^192\\.168(?:\\.[0-9]{1,3}){2}$",
      "^169\\.254(?:\\.[0-9]{1,3}){2}$",
      "^169\\.254\\.169\\.254$",
      "^metadata\\.google\\.internal$"
    ],
    "maxCodeSize": 10485760,
    "fetchTimeoutMs": 30000,
    "requireHash": true,
    "enableCache": true,
    "cacheTtl": 3600
  }
}
```

## CLI Usage

```bash theme={null}
# Direct URL
isol8 run --url https://raw.githubusercontent.com/user/repo/main/script.py --runtime python

# GitHub shorthand (owner/repo/ref/path)
isol8 run --github user/repo/main/script.py --runtime python

# Gist shorthand (gistId/file.ext)
isol8 run --gist abcd1234/example.js --runtime node

# Integrity verification
isol8 run --url https://example.com/script.py --hash <sha256> --runtime python

# HTTP is blocked by default; opt-in per request only
isol8 run --url http://example.com/script.py --allow-insecure-code-url --runtime python
```

## TypeScript API

```ts theme={null}
import { DockerIsol8 } from "@isol8/core";

const isol8 = new DockerIsol8({
  remoteCode: {
    enabled: true,
    allowedSchemes: ["https"],
    allowedHosts: ["^raw\\.githubusercontent\\.com$"],
    blockedHosts: ["^localhost$"],
    maxCodeSize: 10 * 1024 * 1024,
    fetchTimeoutMs: 30_000,
    requireHash: true,
    enableCache: true,
    cacheTtl: 3600,
  },
});

const result = await isol8.execute({
  codeUrl: "https://raw.githubusercontent.com/user/repo/<sha>/script.py",
  codeHash: "<sha256>",
  runtime: "python",
});
```

## Policy Fields

<ResponseField name="remoteCode.enabled" type="boolean" default="false">
  Enables remote source fetching. If false, `codeUrl` requests are rejected.
</ResponseField>

<ResponseField name="remoteCode.allowedSchemes" type="string[]" default="[&#x22;https&#x22;]">
  Allowed URL schemes for source fetches.
</ResponseField>

<ResponseField name="remoteCode.allowedHosts" type="string[]" default="[]">
  Regex allowlist for hostnames. Empty means all hosts are allowed unless blocked.
</ResponseField>

<ResponseField name="remoteCode.blockedHosts" type="string[]" default="[localhost/private ranges/metadata]">
  Regex blocklist for hostnames. Applied before execution to reduce SSRF risk.
</ResponseField>

<ResponseField name="remoteCode.maxCodeSize" type="number" default="10485760">
  Maximum source size in bytes. Fetch aborts if exceeded.
</ResponseField>

<ResponseField name="remoteCode.fetchTimeoutMs" type="number" default="30000">
  Timeout for source download.
</ResponseField>

<ResponseField name="remoteCode.requireHash" type="boolean" default="false">
  Requires `codeHash` on every URL-based execution.
</ResponseField>

<ResponseField name="remoteCode.enableCache" type="boolean" default="true">
  Cache toggle for remote source policy.
</ResponseField>

<ResponseField name="remoteCode.cacheTtl" type="number" default="3600">
  Cache TTL in seconds for remote source policy.
</ResponseField>

## Security Model

Remote source fetching includes:

* Scheme checks (`https` by default)
* Host allow/block regex checks
* DNS/IP checks that block loopback/private/link-local targets
* Size limits and fetch timeout enforcement
* UTF-8 decoding + binary-content rejection
* SHA-256 integrity verification when `codeHash` is provided (or required)

## Interaction With Runtime Network Flags

`remoteCode` controls **pre-execution source download**.\
`--net`, `--allow`, and `--deny` control **network access from code running inside the container**.

They are separate controls and should be configured independently.

## Server Mode

When using `isol8 serve` + `RemoteIsol8`, URL fetching happens on the **server side**.\
The server policy (`remoteCode` in server config) is what enforces URL restrictions.

## Recommended Production Baseline

1. `remoteCode.enabled: true`
2. `allowedSchemes: ["https"]`
3. Restrictive `allowedHosts`
4. `requireHash: true`
5. Conservative `maxCodeSize` and `fetchTimeoutMs`
6. Use immutable references (commit SHAs/tags), not mutable branches