0Pricing
AI Agents · Lezione

Sandbox per agenti basate su Docker

Avvio di container temporanei per eseguire codice generato dall’agente.

Sandbox per agenti basate su Docker è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Perché gli agenti hanno bisogno di sandbox

Quando un agente esegue codice scritto da un LLM, quel codice è non attendibile. Potrebbe tentare di leggere file sensibili, stabilire connessioni in uscita o consumare risorse senza limiti.

Una sandbox isola l'esecuzione del codice, così i danni restano circoscritti indipendentemente da ciò che il codice fa.

Docker come livello di sandbox

I container Docker forniscono un isolamento leggero a livello di sistema operativo. Ogni frammento di codice viene eseguito all'interno di un container nuovo, con limiti espliciti sulle risorse e restrizioni di rete.

L'SDK Python di docker consente di creare ed eliminare container programmaticamente dall'interno dell'agente.

import docker

client = docker.from_env()
print(client.version()['Version'])

Esecuzione di base di un container

client.containers.run() avvia un container, esegue un comando e restituisce l'output come byte. Impostando auto_remove=True, il container viene eliminato dopo la sua terminazione.

import docker

client = docker.from_env()

output = client.containers.run(
    'python:3.12-slim',
    'python -c "print(2 + 2)"',
    auto_remove=True
)

print(output.decode())  # '4'

Limiti di memoria e CPU

Senza limiti, uno script fuori controllo può esaurire la memoria dell'host. Passi mem_limit e nano_cpus per limitare l'uso delle risorse.

Se il processo supera mem_limit, il container viene terminato per esaurimento della memoria (OOM) e viene sollevata un'eccezione.

output = client.containers.run(
    'python:3.12-slim',
    'python -c "x = [0]*10**8"',   # tries to allocate ~800 MB
    mem_limit='256m',
    nano_cpus=1_000_000_000,        # 1 CPU
    auto_remove=True
)
# Raises docker.errors.ContainerError if OOM-killed

Disabilitazione della rete

Impostando network_disabled=True, si impedisce al container di effettuare chiamate di rete in ingresso o in uscita: persino le richieste DNS non vanno a buon fine. In questo modo si bloccano l'esfiltrazione dei dati e le callback verso i server di comando e controllo.

output = client.containers.run(
    'python:3.12-slim',
    'python -c "import urllib.request; urllib.request.urlopen(\"http://example.com\")"',
    network_disabled=True,
    auto_remove=True
)
# Raises ContainerError: network unreachable

Timeout di esecuzione

Un ciclo infinito all'interno della sandbox bloccherebbe l'agente per sempre. Passi un timeout (in secondi) a containers.run() affinché Docker termini il container dopo la scadenza.

import docker
from docker.errors import ContainerError

client = docker.from_env()

try:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "while True: pass"',
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True,
        timeout=30
    )
except Exception as e:
    print(f'Sandbox timeout or error: {e}')

Funzione helper completa per la sandbox

Racchiudere tutte le impostazioni in una funzione riutilizzabile ne facilita la chiamata dagli strumenti dell'agente. Restituisca sia stdout sia un flag di stato, così l'agente può gestire gli errori.

import docker

client = docker.from_env()

def run_in_sandbox(code: str, timeout: int = 30) -> dict:
    cmd = f'python -c "{code.replace(chr(34), chr(39))}"'
    try:
        out = client.containers.run(
            'python:3.12-slim',
            cmd,
            mem_limit='256m',
            nano_cpus=500_000_000,
            network_disabled=True,
            auto_remove=True,
            timeout=timeout
        )
        return {'success': True, 'output': out.decode()}
    except Exception as e:
        return {'success': False, 'error': str(e)}

Montaggio di uno spazio di lavoro temporaneo

Se il codice deve leggere file di input o scrivere file di output, monti una directory temporanea dell'host nel container. Utilizzi volumes con la modalità 'rw' per lo spazio di lavoro e non monti altro.

import tempfile, os

with tempfile.TemporaryDirectory() as tmpdir:
    # Write input data
    with open(os.path.join(tmpdir, 'data.txt'), 'w') as f:
        f.write('hello sandbox')

    output = client.containers.run(
        'python:3.12-slim',
        'python -c "print(open(\"/workspace/data.txt\").read())"',
        volumes={tmpdir: {'bind': '/workspace', 'mode': 'rw'}},
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(output.decode())

File system in sola lettura

Imposti read_only=True per montare il file system radice del container in sola lettura. Il codice può scrivere solo nei volumi montati esplicitamente. In questo modo si impediscono scritture in /etc, /usr o in altri percorsi sensibili all'interno dell'immagine.

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "open(\"/output/result.txt\",\"w\").write(str(1+1))"',
        volumes={tmpdir: {'bind': '/output', 'mode': 'rw'}},
        read_only=True,
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(open(f'{tmpdir}/result.txt').read())  # '2'

Integrazione della sandbox in uno strumento dell'agente

Registri il runner della sandbox come strumento che l'LLM può chiamare. L'agente genera il codice, lo strumento lo esegue in isolamento e l'output viene restituito al passaggio successivo del ragionamento.

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'execute_python',
            'description': 'Run a Python snippet in an isolated Docker sandbox.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'code': {'type': 'string', 'description': 'Python code to execute.'}
                },
                'required': ['code']
            }
        }
    }
]

def handle_tool_call(name, args):
    if name == 'execute_python':
        return run_in_sandbox(args['code'])

Gestione degli errori e pulizia

I container possono non avviarsi se il demone Docker non è in esecuzione o se l'immagine non è memorizzata nella cache. Gestisca sempre docker.errors.DockerException e assicuri che i container vengano eliminati anche in caso di eccezioni.

from docker.errors import DockerException, ImageNotFound

def safe_run(code: str) -> dict:
    try:
        return run_in_sandbox(code)
    except ImageNotFound:
        # Pull the image first
        client.images.pull('python:3.12-slim')
        return run_in_sandbox(code)
    except DockerException as e:
        return {'success': False, 'error': f'Docker unavailable: {e}'}
    except Exception as e:
        return {'success': False, 'error': str(e)}

Quale impostazione della sandbox è più importante per prevenire l'esfiltrazione dei dati?

Una sandbox per agenti deve impedire al codice eseguito di inviare dati sottratti a un server esterno. Quale parametro Docker blocca direttamente l'accesso alla rete in uscita?

Riepilogo della sandbox Docker

Le sandbox basate su Docker offrono agli agenti un ambiente di esecuzione sicuro combinando limiti di memoria e CPU, isolamento della rete, timeout di esecuzione e file system in sola lettura.

Racchiuda queste impostazioni in un helper riutilizzabile ed esponga quest'ultimo come strumento dell'agente, per consentire all'LLM di eseguire in sicurezza codice generato senza mettere a rischio il sistema host.

Domande Frequenti

La lezione «Sandbox per agenti basate su Docker» è gratuita?

Sì — il testo completo di «Sandbox per agenti basate su Docker» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Sandbox per agenti basate su Docker»?

Avvio di container temporanei per eseguire codice generato dall’agente. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Sandbox per agenti basate su Docker»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Sandbox per agenti basate su Docker
  2. Isolamento tramite VM per agenti che eseguono codice con elevati requisiti di sicurezza
  3. E2B e servizi sandbox cloud
  4. Policy di sicurezza per l’esecuzione del codice
← Torna a AI Agents