Self-hosted sandbox

Running your own sandbox is useful when you want full control: custom dependencies baked into the image, offline work, access to local files, or bigger resource limits than the cloud plan allows.

Prerequisites

Docker installed and running
A artifuncs account
An API key with Full access — create one under Settings → API keys and copy it (you'll only see it once). Your sandbox uses this key to download your tool code, which requires the Read funcs permission. A sandbox-only key is not enough — choose Full access, or a custom scope that includes Read funcs.

Run the container

The sandbox image is published to GitHub Container Registry. Pull the latest:

▸bash

docker pull ghcr.io/artifuncs/artifuncs-sandbox:latest

Then run it:

▸bash

docker run -d \
  --name artifuncs-sandbox \
  -p 8700:8700 \
  -e ARTIFUNCS_API_TOKEN=af_your_token_here \
  -e ARTIFUNCS_BACKEND_URL=https://api.artifuncs.com \
  -e SANDBOX_DEV_MODE=true \
  ghcr.io/artifuncs/artifuncs-sandbox:latest

The image exposes port 8700 by default. You can map it to any host port you like — just remember the public URL you pick. To pin a specific build, swap :latest for a version tag like :v2.

SANDBOX_DEV_MODE=true lets the in-browser IDE write to your sandbox — create, edit, and save files. Leave it off if you only want to run tools, not edit them here.

Point artifuncs at your sandbox

Go to Settings → Sandbox.
Switch the sandbox type to Custom sandbox.
Enter the URL your sandbox is reachable at (e.g. http://localhost:8700).
Save.

The status badge will turn green once the sandbox responds to health checks.

Running on localhost? Browsers (Chrome especially) block a public site like artifuncs.com from reaching localhost or local-network addresses until you grant permission. When you enter such a URL, the Sandbox settings panel shows a Grant access button — click it and approve the browser prompt, otherwise the badge stays orange even though the container is healthy.

Environment variables

Variable	Required	Default	Purpose
`ARTIFUNCS_API_TOKEN`	Yes	—	Authenticates the sandbox against the backend when it downloads tool archives
`ARTIFUNCS_BACKEND_URL`	No	`https://api.artifuncs.com`	Where to reach the artifuncs backend
`ARTIFUNCS_AUTH`	No	`true`	Validates the session token your browser sends. Keep it `true` for any sandbox you point the app at; `false` disables the check (local development only)
`SANDBOX_DEV_MODE`	No	`false`	Set to `true` to let the in-browser IDE edit files on your sandbox. Needed to edit tools here — not to run them

Keep ARTIFUNCS_API_TOKEN secret. Anyone with the token can act as your sandbox and pull down your tool code.

Other SANDBOX_* variables exist for advanced multi-tenant / public hosting, but a personal self-hosted sandbox doesn't need them.

How authentication works

Two separate credentials are in play, and it helps to know which is which:

Your API key (ARTIFUNCS_API_TOKEN) lives only inside the container. The sandbox uses it to call the backend — to confirm who owns it and to download your tool archives. It never reaches the browser.
A short-lived session token is minted by the backend for your browser whenever you use the sandbox. The browser sends it to your sandbox with each request; the sandbox calls the backend to verify it and checks that it belongs to the same account that owns the API key. This is the check ARTIFUNCS_AUTH=true turns on.

Running on a different host

If your sandbox lives on a remote machine, three things need to line up:

The sandbox port must be reachable from your browser. Open the firewall or put it behind a reverse proxy with TLS.
ARTIFUNCS_BACKEND_URL must point at an externally reachable backend — the sandbox itself makes outbound calls to download tool archives.
The URL you enter in Settings → Sandbox is the URL your browser will hit, so use the public one (ideally https://).

Cloud vs self-hosted at a glance

	Cloud	Self-hosted
Setup	Zero	Docker + API token
Custom dependencies	No	Yes — build your own image
Offline	No	Yes
Auto-stop on idle	Yes (~10 min)	No — runs as long as the container does
Auth	Managed tokens	Your API key
Cost	Included in plan	Your own machine

Troubleshooting

Status badge is red (Auth failed) Your ARTIFUNCS_API_TOKEN is wrong, expired, or revoked. Create a new one in Settings → API keys and restart the container with the new value.

Badge stays orange after "Start" The sandbox URL isn't reachable from your browser. Check the port mapping, firewall, and that you can curl $SANDBOX_URL/health from the machine running your browser.

Tools fail to deploy with 401 / 403 The sandbox reached the backend but the token was rejected. A 401 means the key is wrong/expired/revoked — rotate it. A 403 usually means the key's scope is too narrow: downloading tool code needs Read funcs, so a sandbox-only key won't work. Recreate it with Full access.

Tool runs time out immediately The sandbox container might be running out of memory. Check docker stats and bump the container's memory limit.