Volter World

Route Python and native clients through a World

A Node preload does not intercept Python, curl, Go or a native binary. Those clients must honor the World's proxy and session CA, or a vendor-supported endpoint override. Being launched in a World does not by itself prove every network call was routed.

A Python request to the real vendor hostname

Use Node 22.6 or newer, npm and Python 3 in an empty directory. The example first creates a customer using the real Node SDK, then reads it from Python through the scoped HTTPS proxy.

package.json
{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.169",
    "@volter/twin-stripe": "3.0.2",
    "@volter/world-core": "3.0.156",
    "@volter/world-runtime": "3.0.166",
    "@volter/world-console": "3.0.152",
    "@volter/world-ui": "1.0.156"
  }
}
.env.example
STRIPE_SECRET_KEY=
check.mjs
import assert from 'node:assert/strict';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { maxNetworkRetries: 0 });
const made = await stripe.customers.create({ email: 'ada@example.com', name: 'Ada' });
assert.equal((await stripe.customers.retrieve(made.id)).email, 'ada@example.com');
assert.equal(made.created, Date.parse('2026-01-15T12:00:00Z') / 1000);
console.log('create, read and frozen timestamp passed');
read-customer.py
import json, os, ssl, urllib.request
proxy = os.environ.get('HTTPS_PROXY') or os.environ.get('https_proxy')
ca = os.environ.get('CURL_CA_BUNDLE') or os.environ.get('SSL_CERT_FILE')
if not proxy or not ca: raise RuntimeError('Expected the World proxy and its session CA')
client = urllib.request.build_opener(urllib.request.ProxyHandler({'https': proxy}), urllib.request.HTTPSHandler(context=ssl.create_default_context(cafile=ca)))
request = urllib.request.Request('https://api.stripe.com/v1/customers', headers={'Authorization': 'Bearer ' + os.environ['STRIPE_SECRET_KEY']})
with client.open(request) as response: customers = json.load(response)
assert any(c.get('email') == 'ada@example.com' for c in customers['data'])
print('Python real-hostname request read the seeded customer')
npm install
./node_modules/.bin/volter world init --name native-client --twins stripe
./node_modules/.bin/volter world up
./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
./node_modules/.bin/volter world run -- node check.mjs
./node_modules/.bin/volter world run -- python3 read-customer.py
Python real-hostname request read the seeded customer

The Python code explicitly uses the inherited proxy and its CA. It calls api.stripe.com, keeps TLS verification enabled, and receives the same stored customer. It uses only Python's standard library. Do not print the proxy environment, bearer keys or CA custody into a bug report.

./node_modules/.bin/volter world log
./node_modules/.bin/volter world down

Use Stripe's Python SDK

For a Python app, use the real SDK rather than replacing its calls with raw HTTP. This example uses Python 3.11 and Stripe's 16.0.0 SDK with its Requests client. Install into a project-owned virtual environment; keep the app's existing pinned World dependencies and selected Stripe service.

requirements-world.txt
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
stripe==16.0.0
typing_extensions==4.16.0
urllib3==2.8.0
python3 -m venv .venv-stripe
.venv-stripe/bin/python -m pip install -r requirements-world.txt

Save an ordinary SDK client. Its API hostname remains api.stripe.com:

customer-sdk.py
import json, os
from stripe import StripeClient
client = StripeClient(os.environ['STRIPE_SECRET_KEY'], max_network_retries=0)
customer = client.v1.customers.create({'name': 'Python SDK user', 'email': 'python-sdk@world.test'})
read = client.v1.customers.retrieve(customer.id)
print(json.dumps({'id': read.id, 'name': read.name, 'email': read.email, 'created': read.created}))

Stripe's Requests client passes stripe.ca_bundle_path explicitly when verifying TLS. It does not rely solely on REQUESTS_CA_BUNDLE. With its default bundled CA, a request through the World proxy fails certificate verification before reaching the customer operation.

Configure the SDK's trust path before the app starts. This small caller-owned bootstrap keeps the app's file and SDK calls intact; it is specific to Stripe's Python client:

stripe-world.py
import os, runpy, sys
from pathlib import Path
import stripe

if not os.environ.get('VOLTER_WORLD'):
    raise RuntimeError('Run through the World.')
proxy = os.environ.get('HTTPS_PROXY') or os.environ.get('https_proxy')
ca = os.environ.get('REQUESTS_CA_BUNDLE') or os.environ.get('SSL_CERT_FILE')
if not proxy or not ca:
    raise RuntimeError('Expected the World proxy and its session CA.')
if len(sys.argv) < 2:
    raise RuntimeError('Usage: python stripe-world.py <app.py> [args...]')

stripe.ca_bundle_path = ca
script = Path(sys.argv[1]).resolve()
sys.argv = sys.argv[1:]
sys.path.insert(0, str(script.parent))
runpy.run_path(str(script), run_name='__main__')
./node_modules/.bin/volter world up
./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
./node_modules/.bin/volter world run -- .venv-stripe/bin/python stripe-world.py customer-sdk.py
./node_modules/.bin/volter world log
./node_modules/.bin/volter world down

The SDK creates and retrieves a stored customer named Python SDK user. The timestamp comes from the frozen World clock, and down retains the record. This covers customer creation and retrieval with the named SDK and transport; it does not establish every Stripe operation or every Python HTTP client. TLS verification stays enabled and no CA is installed system-wide. If your app already configures stripe.ca_bundle_path, supply the World CA through that setting instead of adding this bootstrap. For module or framework entry points, use their supported startup configuration; this bootstrap launches a Python file.

Other clients

Client behaviorConfigureVerify
Honors HTTPS_PROXY and a CA pathRun through the World; select that client's supported trust variable or explicit CA optionA vendor request and expected state/log result
Has its own SDK/CLI endpoint overrideUse the override declared by the twin, such as AWS_ENDPOINT_URLThe selected endpoint, SDK result and log
Ignores proxy variablesSet its documented proxy/CA options, or a supported explicit endpointDo not infer routing from the parent shell
Uses raw sockets, native DNS or an unsupported transportUse the appropriate enforced Machine/executor boundary when isolation is requiredActual boundary evidence; cooperative sandbox alone is insufficient

./node_modules/.bin/volter world shell opens a subshell with World routing. eval "$(./node_modules/.bin/volter world activate)" activates a compatible shell; deactivate restores it. Prefer world run for bounded scripts so the caller's shell is not left activated. Closing a shell does not tear down the World.

A CA trusted through environment variables is scoped to cooperating clients, not installed into the system trust store. Never turn off TLS verification to get a request through. Sandbox mode refuses untwinned destinations in cooperating clients, but cannot constrain a binary that ignores its mediation. See transport coverage, CLI for remote commands, and recovery for diagnostic commands.

View Markdown source

On this page