Secure compute — file work

Module id: compute · Kind: sidecar · Configured by: COMPUTE_URL + COMPUTE_TOKEN, switched on with COMPUTE.ENABLED · Capability: code_run (chat), code_execution (API gateways)

File work lets the assistant run a short Python or Node program on copies of files you already picked, and hand the result back as files. "Turn these three CSVs into one Excel sheet with a chart", "rename every photo in this folder by its date", "convert this JSON export to a table" — that kind of job. The program runs in an isolated sidecar container with a time, memory and output cap; Synaplan itself never touches Docker.

Off by default. When it is off there is no chat card, no Workspace tab and no API teaser — the assistant simply says it cannot run code here and points at Desktop skills instead.

What it adds

  • A "File work" card in chat. The assistant plans the step, runs it, and shows what happened in one sentence: which files were created, or why nothing was saved.
  • Result files in Files. Created files land in your Files list (source File work) and as cards under the answer — download, preview, or hand them to the next step.
  • A persistent workspace (optional). With COMPUTE.WORKSPACES_ENABLED on, each person gets one folder that survives between runs: Files → Workspace, plus an Open workspace link on every finished run.
  • Website access (optional, not yet available). COMPUTE.EGRESS_ENABLED prepares a short, pinned allow-list of public websites a run may reach. See Websites (egress) below for the honest status.
  • code_execution on the API. The Anthropic-compatible and OpenAI-compatible gateways offer the tool to API keys that carry the compute:run grant.
  • Approvals. Unattended runs (Saved Tasks) and any run that would reach a website pause under Approvals first — see Tools & approvals.

Without it

Everything else keeps working. The assistant answers "Can you run code?" with no for this workspace and names the alternative: Synaplan Desktop skills run on the user's own computer. The /api/v1/compute/* routes answer 404 feature_not_configured, so nothing shows a half-working surface.

How to ask

Attach or pick the files, then say what you want in plain language:

  • "Merge these two spreadsheets on the Order ID column and give me one file."
  • "Make a bar chart of monthly revenue from this CSV, as PNG."
  • "Rename the PDFs in my workspace to YYYY-MM-DD_<title>.pdf."
  • "Convert this JSON to CSV and drop the empty columns."

The assistant writes and runs the program for you. You never see or edit code unless you ask to. When the run finishes, the card lists the new files; when it does not, the card says why in one sentence ("File work ran out of time. Nothing new was saved.") and nothing half-finished is stored.

What the assistant can and cannot do here

Can Cannot
Read copies of the files you chose for this run Read any other file of yours, or anyone else's
Write result files (up to the output cap, default 50 MB per run) Change the originals — they are never touched
Use Python 3 or Node.js with their standard libraries Install packages, open a shell, or run as root
Keep files in your workspace between runs (when workspaces are on) Reach the internet — every run is offline today, see Websites (egress) below
Run for up to the time cap (default 60 s, hard maximum 300 s) Keep running in the background or start other programs

Result files and the workspace

Result files are ordinary files in Files with the source File work. They are yours, they can be shared, searched and used in the next chat turn like any upload.

Workspace (needs COMPUTE.WORKSPACES_ENABLED) is one folder per person that the assistant reuses between runs — handy when a job has several steps or when you want the AI to keep working on yesterday's output.

  • Find it: Files → Workspace, or the Open workspace link on a finished run.
  • Use it: each file has Preview (images and text) and Download. The header shows x MB of y MB used.
  • Empty state: "Files the AI creates for you will show up here." with a Back to chat button.
  • Undo: Delete workspace removes the folder after one confirmation — "The AI will start from an empty folder next time." The result files already saved in Files stay.
  • Not indexed. Workspace files are not vectorised or searchable by the AI until you save one through the normal upload path.
  • Size and age. The folder has a size limit per plan (COMPUTE_WORKSPACE_MB, default 256 MB) and an expiry date (WORKSPACE_TTL_DAYS, default 90 days after creation). In this release the expiry is recorded but not enforced automatically — delete the folder yourself when you no longer need it.

Websites (egress)

A run may need to fetch from a website — an open-data API, a currency rate. COMPUTE.EGRESS_ENABLED prepares that: Synaplan reduces every host the assistant names to a bare host name, refuses anything that is not a public address (localhost, private and link-local ranges, shared address space such as 100.64.0.0/10, documentation and benchmarking prefixes), pins the remaining public IPs on port 443, and caps the list (EGRESS_MAX_HOSTS, default 8 — too many hosts refuses the run, the list is never silently shortened).

Two rules always hold:

  • A run that would reach a website asks first (COMPUTE.EGRESS_REQUIRES_APPROVAL, default on). The approval card names the websites: File work — language: python, websites: api.example.com. This ask cannot be skipped by an assistant's "always allow" rule or a Saved Task's unattended setting. If approvals are switched off on the installation, such a run is refused, never run unattended.
  • Off means offline. With the flag off the allow-list is empty and the container has no network at all.

Status today: the sidecar shipped with Synaplan reports features.egress: false — it creates every container without a network and refuses any non-empty allow-list. The admin UI therefore refuses to switch COMPUTE.EGRESS_ENABLED on ("Website access for file work is not offered by this installation's compute sidecar yet. The switch stays off.") until a sidecar release with the egress proxy is connected. Everything on the Synaplan side is in place for that release.

How to enable

File work needs two things: the compute sidecar reachable from the backend, and the COMPUTE.ENABLED flag. One without the other is Needs setup / off, never a teaser.

1. Run the sidecar

Developer / evaluation stack (same host, Compose profile compute — tier T1, a hardened Docker container):

make -C sidecars/synaplan-compute images            # build the Python and Node runner images once
COMPUTE_TOKEN=$(openssl rand -hex 32) \
COMPUTE_URL=http://compute:8080 \
COMPUTE_DOCKER_GID=$(stat -c %g /var/run/docker.sock) \
docker compose --profile compute up -d

The token must be at least 32 random bytes; the sidecar refuses to start with a weak one. Never publish port 8080 — only the backend and worker talk to it. The runner never pulls images: build them first or the first run fails with image not found.

Production uses tier T2: the same API behind the gVisor runsc runtime on a separate compute node (its own host or Docker daemon), never on the web nodes that serve users. The layout for the hosted platform lives in the private platform repository; self-hosters follow the sidecar's own deployment notes in sidecars/synaplan-compute/.

2. Point the backend at it

COMPUTE_URL=http://compute:8080
COMPUTE_TOKEN=<the same token>

Set both on backend and worker and restart them. Operate → Feature Status → Secure compute should now read Secure compute is running; COMPUTE.ENABLED is off.

3. Switch it on

Operate → System configuration → Processing → File work → COMPUTE.ENABLED, or pin it for automated deployments with FEATURE_COMPUTE_ENABLED=true. Feature Status changes to Secure compute is running; the assistant starts offering file work in chat.

Workspaces (COMPUTE.WORKSPACES_ENABLED) and websites (COMPUTE.EGRESS_ENABLED) are separate switches in the same section, both off by default. Either can only be switched on when the connected sidecar reports the feature in its health check (features.workspaces, features.egress).

Turning it off deliberately

COMPUTE_URL=disabled

or switch COMPUTE.ENABLED off. Runs in progress finish; new ones are not offered.

Check it works

  • Operate → Feature Status → Secure compute shows Available / Secure compute is running. The probe is GET /v1/health on the sidecar.
  • GET /api/v1/config/runtime reports features.computeEnabled: true (and features.computeWorkspacesEnabled when workspaces are on).
  • In chat, ask "Can you run code?" or type /help — the live inventory lists File work as available.
  • Attach a CSV and ask for a chart. A card appears, and a PNG lands in Files.

Limits and quotas

Every run is capped. Instance defaults sit under Processing → File work and are refused on save when they exceed what the sidecar's health check allows:

Setting Default Meaning
DEFAULT_TIMEOUT_SEC / MAX_TIMEOUT_SEC 60 / 300 Wall-clock time per run; the assistant may ask for less, never more
DEFAULT_MEMORY_MB 512 Memory per run
DEFAULT_CPU 1.0 CPU cores per run
DEFAULT_PIDS 128 Processes per run
DEFAULT_OUTPUT_MB 50 Total size of result files per run

Per-plan quotas live in the rate-limit groups (RATELIMITS_<LEVEL>, see Administration):

Key What it caps Defaults
COMPUTE_RUNS_* Runs per hour / total new accounts 5 total; Pro 10/h, Team 30/h, Business 100/h; anonymous 0
COMPUTE_CPU_SECONDS_DAILY CPU-seconds per day 60 · Pro 300 · Team 900 · Business 3600
COMPUTE_CONCURRENT Runs at the same time 1 · Pro 2 · Team/Business 4
COMPUTE_WORKSPACE_MB Size of the persistent folder 256 · Pro 512 · Team 1024 · Business 2048

Hitting a limit ends the run with one sentence ("You have used this week's file-work limit. Nothing new was saved."), never an HTTP code.

Policy and who may use it

  • Interactive (the owner is in the chat): default auto — runs without asking.
  • Unattended (a Saved Task): default approve — pauses under Approvals.
  • Assistants stay opted out until code_run is listed in their skills; an assistant cannot loosen the instance policy.
  • API keys need the compute:run grant to see code_execution on the gateways.
  • Audit. Every run writes one row (owner, limits, workspace id, websites, sidecar run id, exit code, duration) — no code, no file contents. Pending asks are rows under Approvals.

Configuration reference

Variable / setting Default Meaning
COMPUTE_URL empty Base URL of the sidecar. Empty or disabled = module absent.
COMPUTE_TOKEN empty Shared bearer token, ≥ 32 random bytes. Both must be set for the module to count as configured.
COMPUTE.ENABLED (FEATURE_COMPUTE_ENABLED) off The product switch.
COMPUTE.WORKSPACES_ENABLED (FEATURE_COMPUTE_WORKSPACES_ENABLED) off Files → Workspace and Open workspace.
COMPUTE.EGRESS_ENABLED (FEATURE_COMPUTE_EGRESS_ENABLED) off Website allow-list; cannot be switched on until the sidecar offers egress.
COMPUTE.EGRESS_REQUIRES_APPROVAL on Any run with websites asks first.
COMPUTE.EGRESS_MAX_HOSTS 8 More hosts than this refuses the run.
COMPUTE.WORKSPACE_TTL_DAYS 90 Expiry recorded on each workspace (not yet enforced automatically).
COMPUTE.POLICY_INTERACTIVE / POLICY_UNATTENDED auto / approve Policy defaults per context.

Sidecar-side variables (COMPUTE_AUTH_TOKEN, COMPUTE_DOCKER_GID, caps, retention) are documented with the sidecar in sidecars/synaplan-compute/.

Troubleshooting

  • Feature Status: Secure compute is not reachable. The sidecar is down or the URL is wrong. docker compose --profile compute logs compute; check GET $COMPUTE_URL/v1/health from inside the backend container.
  • Secure compute is running; COMPUTE.ENABLED is off. Expected until you flip the flag (step 3).
  • Every run fails with image not found. Build the runner images: make -C sidecars/synaplan-compute images.
  • "File work is not available on this installation." The flag is off for this user or the module is absent. Check Feature Status.
  • No Workspace tab. COMPUTE.WORKSPACES_ENABLED is off, or the sidecar does not report features.workspaces.
  • "Website access … not offered by this installation's compute sidecar yet." Expected with the shipped sidecar; see Websites (egress) above.
  • "Reaching a website from file work needs your approval, and approvals are off." Switch TOOLS.APPROVALS_ENABLED on, or leave COMPUTE.EGRESS_REQUIRES_APPROVAL on and accept that such runs are refused — they never run unattended.
  • Quota sentences. "You have used this week's file-work limit." — raise the COMPUTE_* keys for that plan under Administration, or wait for the window to reset.

Related