Safely connect AI to your enterprise data

How does Spice sandbox AI agents?

Spice sandboxes the data an AI agent can reach, not the code the agent runs. Each agent, or each tenant, gets its own Spice runtime. That runtime holds a filtered, read-only copy of the data the agent needs, so the agent never connects to the production database. Spice builds the sandbox in four steps:

1. Declare: the agent's spicepod.yaml lists the datasets, models, and tools that the agent can use. A dataset that the Spicepod does not declare is not in the runtime catalog.
2. Filter: the refresh_sql setting on each accelerated dataset selects the rows and columns that Spice copies from the source. Spice sends the filter to the source, so other rows stay in the source database. With the default settings, the agent reads only this local copy.
3. Scope: a model gets only the tools in its tools parameter, and its tools query only the datasets in its datasets list. A model with no tools parameter gets no Spice tools.
4. Trace: task history records each SQL query, model call, and tool call in the spice.runtime.task_history table.

The following Spicepod gives one tenant's agent a read-only copy of that tenant's orders:

version: v1
kind: Spicepod
name: tenant-acme-agent

datasets:
  - from: postgres:public.orders
    name: orders
    params:
      pg_host: ${secrets:PG_HOST}
      pg_db: app
      pg_user: ${secrets:PG_USER}
      pg_pass: ${secrets:PG_PASS}
      pg_sslmode: verify-full
    acceleration:
      enabled: true
      engine: duckdb
      mode: file
      refresh_check_interval: 10m
      refresh_sql: |
        SELECT order_id, status, total, created_at
        FROM orders
        WHERE tenant_id = 'acme'

models:
  - name: agent
    from: openai:gpt-4o-mini
    datasets:
      - orders
    params:
      openai_api_key: ${secrets:OPENAI_API_KEY}
      tools: list_datasets, table_schema, sql

To require an API key, set runtime.auth.api_key.enabled: true and list the key under runtime.auth.api_key.keys in the same Spicepod, as the authentication docs show. A key is read-only unless it ends in :rw. The agent then calls Spice with that key instead of database credentials:

curl http://localhost:8090/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $SPICE_AGENT_API_KEY" \
  -d '{"model": "agent", "messages": [{"role": "user", "content": "How many orders are still open?"}]}'

The multi-tenant agents guide compares this pattern with the other isolation options. For a step-by-step walkthrough, read how to sandbox data access for AI agents.

What does each sandbox control limit?

Each control is a Spicepod setting. The defaults below apply when the setting is not present:

The refresh_sql filter is a boundary only while queries stay on the local copy. These settings send queries to the source table instead: ready_state: on_registration or on_schema_resolved before the first load, on_zero_results: use_source when the local copy returns no rows, and refresh_mode: caching on a cache miss. Keep the defaults (on_load and return_empty) for a sandbox. For a hard boundary, also connect Spice with a database user or view that can read only the tenant's rows. The two retention rows run only when acceleration.retention_check_enabled is true and retention_check_interval is set. TLS is off by default. Set runtime.tls.enabled: true before an agent connects to Spice over a network. Spice does not encrypt accelerated data at rest, so put file-mode accelerators on an encrypted volume. To keep the audit trail longer than 8 hours, set runtime.task_history.retention_period or export traces with OpenTelemetry.

How is a Spice sandbox different from a code sandbox?

A code sandbox, such as a container, a microVM, or a WebAssembly runtime, limits what an agent's code can do on a host. A Spice sandbox limits the data an agent can read and the tools it can call. Most production agents need both. Run the agent's code in a code sandbox, and send its data access through a Spice runtime. The Spice Docker image runs as a non-root user, which also limits the runtime itself.

What does Spice.ai Enterprise add to the sandbox?

The open-source runtime scopes access with dataset lists, read-only keys, and model allowlists. It has no row-level or role-based policy engine. Spice.ai Enterprise adds:

• Policies: Cedar authorization policies apply row filters, column masks, and roles to datasets, models, tools, and endpoints.
• Identity: OIDC authentication, in preview, maps each caller to a principal that the policies evaluate.

For agents that reach external systems, the MCP server gateway puts MCP tools under the same model tools list. To run the sandbox as a managed service, compare Spice Cloud and Enterprise plans.