Ink Python SDK

Create secure, short-lived sandboxes from Docker/OCI images. This first release contains only the sandbox API.

Install

pip install "mldotink-sdk @ git+https://github.com/mldotink/sdk-python.git"

Set INK_API_KEY, or pass api_key to Ink.

Run code in a sandbox

from ink import Ink

with Ink() as ink:
    sandbox = ink.sandboxes.create(
        image="python:3.12",
        vcpus=1,
        memory_gb=2,
        allow_domains=["api.openai.com"],
        destroy_timeout_seconds=900,
    )

    sandbox.files.write_text("/workspace/main.py", "print('hello from Ink')")
    result = sandbox.commands.run(
        ["python", "/workspace/main.py"],
        timeout_seconds=60,
    )
    print(result.stdout)

    metrics = sandbox.metrics()
    print(metrics.cpu_usage.data_points)
    sandbox.terminate()

project and workspace are optional. When omitted, Ink uses the account's defaults. For shell syntax, use sandbox.commands.run_command("..."); the preferred run([...]) form executes an argv array without a shell.

Private ports

session = sandbox.ports.connect(8000, expires_in_seconds=300)
print(session.url)

The URL is a short-lived authenticated session. Sandbox ports are not exposed directly.

Commands have both a server execution timeout and a bounded client wait. By default, run() waits for the requested execution timeout plus 30 seconds. If polling times out, SandboxCommandTimeoutError.command retains the execution ID so it can be inspected or cancelled. Cancelling a running command hard-stops its entire sandbox.

Network access

Pass allow_domains to restrict outbound traffic:

sandbox = ink.sandboxes.create(
    image="python:3.12",
    vcpus=1,
    memory_gb=2,
    allow_domains=["api.openai.com", "*.githubusercontent.com"],
)

This selects allowlist egress explicitly. Use network_egress="none" for no outbound traffic or "public" for unrestricted public egress.

Refreshing state

Sandbox state is exposed as an immutable snapshot. refresh(), update(), and terminate() replace that snapshot only after the complete API response has been validated:

sandbox.refresh()
print(sandbox.state)
snapshot = sandbox.info

Safe mutation retries

Create, command, and port operations accept an idempotency_key. The SDK generates one when omitted and reuses it for automatic retries. If the network fails after all retry attempts, AmbiguousOperationError.idempotency_key contains the key needed to retry the same operation safely.