Sandbox overview

A sandbox is the isolated environment where your tools actually run. Every time you execute a tool on artifuncs, the code is deployed to a sandbox, spun up in its own process, given a short‑lived auth token, and streamed logs back to the UI.

Why sandboxes?

Tools are user‑authored code — anything from a JSON formatter to a script that calls an external API. Running that code safely means it needs to be:

• Isolated — one user's tool can't read another user's files or state
• Bounded — memory, CPU, and runtime are capped
• Reproducible — the same tool behaves the same way on every run
• Disposable — a sandbox can be thrown away and recreated at any time

A container gives us all four, and the sandbox is simply a container running a small FastAPI service that knows how to install and execute tools on demand.

What's inside

Every sandbox ships with:

• A Python 3.11+ runtime and a Node.js runtime — tools can be written in either
• The artifuncs SDK, which gives tools file I/O, logging, and environment access
• A tool manager that downloads tool archives from the backend and sets them up
• A worker pool that keeps recently‑used tools warm for fast re‑runs

You never have to manage any of this yourself — the sandbox handles it transparently.

Two flavours

artifuncs supports two kinds of sandboxes:

You can switch between them from Settings → Sandbox at any time. Your tools and their settings are stored in the backend, so switching doesn't lose anything.

How it connects

Your browser  ──GraphQL──▶  artifuncs backend
     │                          │
     └──HTTP / WebSocket──▶  Sandbox (cloud or local)
                                │
                                └──pulls tool archives──▶  backend

When you run a tool, the browser talks directly to the sandbox over HTTP or a WebSocket. The backend stays in the loop only for coordination — starting the sandbox, issuing short‑lived session tokens, and serving tool archives.

Next up: Managing your sandbox.