Gateways

Gateways control how your sandbox connects to external services. They provide network policies and automatic credential injection, making it easy to securely access APIs, databases, and other services from your sandbox.

What Gateways Do

When you configure a gateway profile, Islo:

1. Applies network policies - Controls which external endpoints your sandbox can reach
2. Injects credentials - Automatically provides API keys, tokens, and secrets
3. Routes traffic - Can proxy requests through specific endpoints

This means your sandbox gets secure access to external services without you manually managing credentials or network configuration.

Using Gateways

Via CLI Flag

Specify a gateway profile when using a sandbox:

$
islo use my-sandbox --gateway-profile production-apis

Via islo.yaml

Set a default gateway for your project:

1
sandbox: my-project
2
gateway_profile: production-apis

Then all islo use commands will use that gateway:

$
islo use my-sandbox  # Uses production-apis gateway

Overriding Config

The CLI flag overrides islo.yaml:

$
# Uses staging-apis even if islo.yaml says production-apis
$
islo use my-sandbox --gateway-profile staging-apis

Common Use Cases

API Access

Your gateway can provide API access for services your code needs:

$
islo use my-sandbox --gateway-profile openai-access

Your code can make API calls normally - the gateway handles authentication at the network level:

1
# No API key needed in your code or environment
2
client = OpenAI()  # Gateway authenticates requests transparently
3
response = client.chat.completions.create(...)

Database Connections

Access databases through gateway-controlled connections:

$
islo use my-sandbox --gateway-profile prod-db-readonly

The gateway handles:

• Authentication at the connection level
• Routing through secure tunnels
• Enforcing read-only access policies

Third-Party Services

Access external services with pre-configured credentials:

1
sandbox: integration-tests
2
gateway_profile: third-party-sandbox

$
# Run tests against external APIs
$
islo use integration-tests -- pytest tests/integration/

Security Considerations

Gateways are designed for security:

• Credentials are never exposed - Authentication happens at the host/network level, not in the sandbox environment
• Network policies prevent leakage - Sandboxes can only reach approved endpoints
• Audit logging - All external access is logged
• Scoped access - Different profiles for different access levels

Best Practices

1. Use the least privileged gateway - Don’t use production-apis when staging-apis works
2. Set gateway in islo.yaml - Makes it clear what access the project needs
3. Document gateway requirements - Help teammates know which profile to use

Configuration Reference

In islo.yaml

1
# Gateway profile name
2
gateway_profile: my-gateway-profile

CLI Options

Precedence

1. CLI flag (--gateway-profile) - highest priority
2. islo.yaml (gateway_profile field)
3. No gateway (default)

Troubleshooting

”Gateway profile not found”

The specified profile doesn’t exist or you don’t have access:

$
# Check spelling
$
islo use my-sandbox --gateway-profile prodution-apis  # typo!

Connection Refused

The gateway’s network policy may not allow the endpoint:

• Verify the endpoint is included in the gateway’s allowlist
• Check if you need a different gateway profile

API Calls Failing Authentication

Requests aren’t being authenticated by the gateway:

• Confirm the gateway is configured for that service
• Check if you’re using the correct gateway profile
• Verify the endpoint is included in the gateway’s scope