Skip to main content
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)
code and codeUrl are mutually exclusive. Use one or the other per execution request.

​
Enable In Config

Remote URL fetching is disabled by default. Enable it in isol8.config.json: 
{
  "$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

# 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

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

​
remoteCode.enabled
boolean
default:"false"
Enables remote source fetching. If false, codeUrl requests are rejected.
​
remoteCode.allowedSchemes
string[]
default:"[\"https\"]"
Allowed URL schemes for source fetches.
​
remoteCode.allowedHosts
string[]
default:"[]"
Regex allowlist for hostnames. Empty means all hosts are allowed unless blocked.
​
remoteCode.blockedHosts
string[]
default:"[localhost/private ranges/metadata]"
Regex blocklist for hostnames. Applied before execution to reduce SSRF risk.
​
remoteCode.maxCodeSize
number
default:"10485760"
Maximum source size in bytes. Fetch aborts if exceeded.
​
remoteCode.fetchTimeoutMs
number
default:"30000"
Timeout for source download.
​
remoteCode.requireHash
boolean
default:"false"
Requires codeHash on every URL-based execution.
​
remoteCode.enableCache
boolean
default:"true"
Cache toggle for remote source policy.
​
remoteCode.cacheTtl
number
default:"3600"
Cache TTL in seconds for remote source policy.

​
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.
  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