Quick Start | Synapse

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

Each button you press shows the command it ran, and its output, in the command console at the bottom of the screen. Every step below lists that command too. You can copy a command from the console and run it again. IDs, paths, numbers and role names are examples.

Step 1: Sign in and set your password

Open the portal address, enter the ID and temporary password from the note in “ID” and “Password”, and press [Sign in].
If your institution asks for an authenticator app, the “Set up an authenticator app” page comes first. Press [Set up], scan the QR code with the app on your phone, enter the 6-digit code it shows and press [Confirm]. The button then becomes [Change password]: press it.
On the page that asks for a new password, enter the temporary password in “Current password”, your new one in “New password” and “New password again”, and press [Change password]. Then sign in again with the new password, and with a code if you set up the app.

What you see

This is your first sign-in, or an admin created a temporary password. Choose a new password to continue.

In the console

The sign-in pages have no command console. Once you are signed in, the console sits under every screen.
More: Signing in and the authenticator app
Step 2: Connect Claude (once)
In the menu on the left, press [My account] and go to the Claude section.
On your own computer, run the command below in a terminal. When a browser opens, approve with your Claude account, then copy the token the terminal prints.

In a terminal on your computer
$ claude setup-token
Paste the token into “Claude token (sk-ant-...)” and press [Connect Claude]. Every workspace uses this connection.

What you see

This connects your personal Claude account. Data terms, such as whether conversations may train models, follow your own Claude account settings, and the institution cannot set them. Check your Claude privacy settings before connecting.

In the console

The token goes in on standard input, so its value never shows in the console.
Command console App in development
$ synapse user claude-token Done

stdin: (hidden)Connected Claude.
This is an example, drawn from the app in development.
More: Connecting your coding agent
Step 3: Look around My data

[My data] in the menu lists only the data you may see. Data you may not see is not listed at all.
Choose an item to see its “Path in a workspace”, such as /data/images/ct_2024. That is the exact path to give Claude.
If something you need is missing, send an admin what you need and your ID.
In the console

This screen fills itself with read commands and changes nothing. Turn on [Show queries] in the console to see them, such as lake show /.
More: Creating a workspace
Step 4: Create a workspace
In [My workspaces], press [New workspace].
Under “Data this workspace uses”, choose only what this project needs. “All my data” is chosen to start with.
As you choose, “Who can see this workspace's results” changes at once: the more data you choose, the fewer people can see the results. Point at an item and the screen tells you how the number would change before you add it.
Fill in “Name (optional)” if you like, and press [Create workspace].
New workspace App in development
Data this workspace uses

(partly chosen)All my data

(chosen)/images/ct_20241,248 files

(chosen)/tables/patients4 files

(not chosen) (previewing)/tables/labs4 files

Visible files1,252

Who can see this workspace's results

4 of 31 people

Admins can always see

Adding this data narrows who can see the results from 4 to 2: /tables/labs

Roles needed one ofct_researchorimaging_all and one ofehr_basicorehr_full

Name (optional) A name to find it by in your list.
Create workspace
Runs when pressed
$ ws create kim --data /images/ct_2024 /tables/patients

The pointer rests on /tables/labs: the two people who would no longer see the results are hatched. This is an example, drawn from the app in development.
In the console

With “All my data” left as it is, the command carries no data list. A name adds --name.
Command console App in development
$ ws create kim --data /images/ct_2024 /tables/patients Done

Created workspace: ws-0012 (1,252 visible files)Who can see this workspace's results: 4 of 31 people. Admins can always see.Condition: one of ct_research or imaging_all and one of ehr_basic or ehr_fullInternet rules: Packages (packages)
This is an example, drawn from the app in development.
More: Creating a workspace
Step 5: Start it and open the IDE
Choose the new workspace in the list and press [Start]. When its status goes from “Starting” to “Running”, press [Open IDE].
A VS Code–compatible editor (code-server) opens in a new browser tab, with two folders:
- My work: your work folder, ~/project
- My data (read-only): your data, /data
Closing the IDE tab does not stop the workspace, and jobs running in its terminals carry on.
In the console

The first start also prints a line that creates the environment (... Creating the environment, with the environment image's name). [Open IDE] opens a new tab rather than running a command, so it does not appear in the console.
Command console App in development
$ ws start ws-0012 Done

... Preparing the workspace network... Checking the internet proxy and gateway... Starting the environmentStarted workspace: ws-0012IDE: https://app.example.org/ws/ws-0012/open
This is an example, drawn from the app in development.
More: Working in the IDE and terminal
Step 6: Work with 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. Tell it what you want to do.
Every workspace gives Claude the same workspace rules: read data from /data, keep code in ~/project and outputs in ~/project/outputs, fix random seeds, and write the commands that rebuild the outputs from scratch to ~/project/reproduce.sh. For tables, it is told to read the table.yaml in the same folder first.
Neither you nor the agent can edit the rules file, but nothing guarantees that Claude followed it. Open the reproduce script and check it before you release.
~/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
```
In the console

This step uses no buttons, so the console shows nothing new.
More: Working in the IDE and terminal
Step 7: When you need more data
Tell Claude what data you need. Claude first checks how adding it would change who can see the results, then makes a request to add it and gives you an approval link. The data appears in /data only after you approve.
Open the link, or open the request under [Approvals] in the menu. “What changes” shows the visible files and who can see the results, “Now” and “If approved”. If it looks right, press [Approve and run]: the requested command runs once, as you.
To add data yourself, press [Add data] on the workspace. That runs at once, without an approval.
Data you have added cannot be taken out again. To work without it, create a new workspace.

Approvals App in development

Request to add data a-0031

Claude wants to add data to this workspace.

Workspace
ws-0012

Data to add
/tables/labs (4 files)

What changes
When Visible files Who can see

Now 1,252 4 of 31 people

If approved 1,256 2 of 31 people

Command to run
$ ws add-data ws-0012 /tables/labs

Approving runs the command above once, as kim.

If files change or are added after the request, approving does not run it.

Approve and runReject

The page behind the approval link the agent hands you. This is an example, drawn from the app in development.

In the console

The approval page runs the requested command with its approval ID added (--approval a-0031).
Command console App in development
$ ws add-data ws-0012 /tables/labs --approval a-0031 Done

Added data: /tables/labs (1,256 visible files)Who can see this workspace's results: 2 of 31 people. Admins can always see.Condition: ehr_full and one of ct_research or imaging_allRan the approved request: a-0031
This is an example, drawn from the app in development.
More: Approving agent requests
Step 8: Release outputs
On the workspace, press [Release outputs].
Under “Files to release”, give paths relative to the work folder. In the IDE, ~/project/outputs/model.pt is project/outputs/model.pt.
Under “Reproduce command”, give the reproduce script, project/reproduce.sh. “Who can see” in the dialog shows who will be able to see this release.
If you leave it to Claude, it makes a release request, which runs once you approve it as in step 7.
In the console

The work folder and the environment are saved together at the moment of release. The workspace pauses for a moment while that happens, and the console also prints a line with the length of the pause; it is left out here.
Command console App in development
$ release create --workspace ws-0012 --outputs project/outputs/model.pt project/outputs/roc_curve.png --reproduce project/reproduce.sh Done

... Recording the input data... Saving the work folder and environment... Working out who can see it... Registering the outputsReleased: r-0139Who can see this release: 2 of 31 people. Admins can always see.Condition: ehr_full and one of ct_research or imaging_all
This is an example, drawn from the app in development.
More: Releasing outputs
Step 9: Share the link
When it is done, “Just released” offers [Copy share link]. You can also copy it from “Released by me” under [Releases] in the menu. A share link looks like this: https://app.example.org/r/r-0139
A link is an address, not a permission. Whoever gets it still needs permission to open it, and the system checks each time it is opened. People who may not see it are shown the roles needed and [Ask an admin].

What you see

Whoever gets the link still needs permission to open it.

In the console

Copying a link runs no command. When someone without access presses [Ask an admin], their console shows a command like this.
Command console App in development
$ release request-access r-0139 Done

Requested access: r-0139
This is an example, drawn from the app in development.
More: Share links and access requests
Step 10: Stop when you are done
On the workspace, press [Stop]. Every program and terminal running in the environment ends, tmux and screen sessions included; the work folder and what you installed stay. Press [Start] later to carry on.
Archive a workspace you no longer use: stop it, then press [Archive]. The work folder, records and releases stay, and you can restore it.
In the console
Command console App in development
$ ws stop ws-0012 Done

Stopped workspace: ws-0012The work folder stays as it is.
This is an example, drawn from the app in development.
More: Stop, archive and storage

What changes
When	Visible files	Who can see
Now	1,252	4 of 31 people
If approved	1,256	2 of 31 people

Step 1: Sign in and set your password

Step 2: Connect Claude (once)

Step 3: Look around My data

Step 4: Create a workspace

Step 5: Start it and open the IDE

Step 6: Work with Claude Code

Step 7: When you need more data

Step 8: Release outputs

Step 9: Share the link

Step 10: Stop when you are done

Read next