Working in the IDE and terminal

The portal screens are in development. Their words and layout may still change; the commands behind the buttons are already built.

Once a workspace is running, you work as you already do: a VS Code–compatible editor in the browser, a terminal and Claude Code. This page collects what is worth knowing inside a workspace.

Opening the IDE

When the workspace is “Running”, [Open IDE] opens a VS Code–compatible editor (code-server) in a new browser tab. Each press opens another tab, and several tabs are fine. The IDE's menus are in English.

Each workspace has its own web address, so a page opened in one workspace cannot reach another workspace or the portal.

If it does not open, a page says why. For example, “The workspace is not running: ws-0012” means: start it in the portal, then open it again.

The two folders

Your work folder is the whole home folder, ~. Python packages you install, settings and your Claude conversations (~/.claude) live there too, and are saved with every release. The work folder has a size limit.

You cannot write to /data. If you need a changed version of a source file, create it under ~/project. Do not copy source data wholesale into your work folder; read it from /data when you need it.

You can open and download files in the IDE. File transfers through the IDE are recorded.

Claude Code

Open the Claude Code panel in the IDE, or run claude in a terminal. It is already signed in with the token you connected.

Every workspace gives Claude the same workspace rules, and neither you nor the agent can edit them:

• read data from /data;
• keep code under ~/project, and outputs (models, figures, tables, metrics) under ~/project/outputs;
• fix random seeds;
• when producing results, write the commands that rebuild them from scratch to ~/project/reproduce.sh;
• for a table, read the table.yaml in its folder first;
• report a blocked internet address instead of working around it;
• only request adding data or releasing outputs; they run after you approve.

Following the rules is up to the model. Check the code and the reproduce script Claude writes.

The workspace info file, /run/synapse/workspace.json, lists this workspace's data and internet rules; Claude reads it too. To point Claude at data, use the “Path in a workspace” that [My data] shows.

The reproduce script

A release needs a reproduce script: a shell script with the commands that rebuild the outputs from scratch, usually ~/project/reproduce.sh.

#!/bin/sh
# Rebuilds the outputs from scratch (example)
set -e
cd ~/project
pip install --user scikit-learn==1.5.2
python train.py --seed 0 --data /data/images/ct_2024 --out outputs/
python evaluate.py --checkpoint outputs/model.pt --out outputs/roc_curve.png

A good reproduce script:

• fixes random seeds;
• reads data from /data;
• installs the packages it needs, with their versions;
• writes the outputs under ~/project/outputs.

Today a release checks only that the file exists; it does not run it.

Reading tables

A table is a folder of Parquet files, /data/tables/<table>/. The table.yaml in the same folder gives each column's meaning, units, code system and missing-value rules, so read it first.

You can also use DuckDB. Every workspace has a DuckDB file in which each table is ready under its own name; open it read-only.

import duckdb

con = duckdb.connect("/home/researcher/.synapse/data.duckdb", read_only=True)
con.sql("select count(*) from patients").show()

That file is rebuilt whenever the workspace's data changes, so keep tables you create in a file of your own.

Installing packages

Python packages go into your work folder, so they survive a recreated environment:

System packages come from the Ubuntu repositories:

• Packages installed with sudo apt-get install are recorded and installed again when the environment is recreated. The environment saved with a release keeps them exactly as installed.
• If your results depend on a package, put its install command in the reproduce script too.
• Do not use sudo pip.
• Reaching a package repository needs this workspace's internet rules to allow it. The default rule, “Packages”, opens PyPI, Ubuntu apt and VS Code extensions.
• VS Code extensions come from Open VSX. Some Microsoft-only extensions are not there, and a workspace on the “Claude only” rule cannot install extensions.

Long jobs

Closing the IDE tab does not end its terminals: reopening re-attaches the same terminals, with their last 100 lines. Jobs inside tmux or screen also survive an IDE restart, so run anything that takes hours inside one of them.

Press Ctrl+B, then D, to detach. To attach again:

Nothing stops a workspace because it is idle. Pressing [Stop], on the other hand, ends everything, tmux and screen sessions included.

GPUs

An admin sets a GPU memory limit for each workspace; several workspaces may share one GPU. At 90% of the limit, a warning line is added to the workspace's notice file (/run/synapse/gpu-notice.txt), which Claude can read too. Past the limit, the workspace's largest process is ended. The workspace's “GPU memory” shows the use and the limit.

If a process is ended because memory ran out, the workspace shows “A process was ended for lack of memory”. The environment keeps running.

When an address is blocked

A workspace cannot reach the internet directly. It goes out only through a proxy, under the internet rules an admin sets for that workspace. You can see this workspace's rules under “Internet rules” on the workspace.

Blocked requests are listed as “Blocked” in the “Internet access log”, which [View access log] opens; “Blocked only” filters them. If your work needs a blocked address, send it to an admin. A rule change applies at once, even to running workspaces.

at                workspace  method   target                      status  allowed2026-10-22 09:07  ws-0012    CONNECT  huggingface.co:443          403     no2026-10-22 09:31  ws-0012    CONNECT  github.com:443              403     no

Programs that follow the proxy settings, such as git, pip and curl, just work. Some, such as ssh, need their own proxy setting. Workspaces cannot look up external DNS names themselves.

Commands inside a workspace

In a workspace terminal, synapse help lists the commands you can use there, with their usage. Leave out the workspace argument and it means this workspace.