This page covers running all of Claude Science on a remote machine. To keep Claude Science on your own computer and have it run jobs on a machine you reach over SSH, see Remote compute clusters.
Install dependencies
Claude runs code inside a sandbox, and the sandbox needs two system packages: bubblewrap and socat. Installing them takes administrator (sudo) access. Without it, see Run Claude Science without administrator access.
On Fedora, RHEL, or Arch, use the command for your distribution from the Linux tab of Install. On Ubuntu or Debian, run:
The sandbox requires bubblewrap 0.8.0 or later; check with
/usr/bin/bwrap --version. Ubuntu 24.04 ships a new enough version, and Ubuntu 22.04 doesn’t. If Claude Science can’t set up the sandbox, it refuses to start rather than run code unsandboxed.Run Claude Science without administrator access
If you don’t have administrator (root orsudo) access to a shared server or cluster, choose one of these:
- Ask the server’s administrator to set up what the sandbox needs: bubblewrap 0.8.0 or later and socat, installed for the whole system (from the distribution’s packages, or by root in
/usr/local/bin), and a kernel that allows unprivileged user namespaces. - Approve a copy of your own. In version 0.1.71 and later, Claude Science can run bubblewrap and socat that you installed yourself, once you approve them.
- Use the server as an SSH host. Install Claude Science on your own computer and add the server as an SSH host (see Remote compute clusters), if your organization allows SSH hosts. Claude runs jobs on the server under your own account, with your approval. Jobs run outside the sandbox, so the server doesn’t need bubblewrap, socat, or the kernel setting, and you don’t need administrator access there.
sudo. The installer puts the claude-science command in ~/.local/bin, or in another folder you own if you export CLAUDE_SCIENCE_INSTALL_DIR with that folder’s path before you run it.
If you run Claude Science on a cluster’s login node, these points differ from a server you have to yourself:
- Check your site’s rules first. Claude runs its analysis code on the machine where Claude Science runs, and many sites limit long-running or heavy work on login nodes.
- Choose your own port, because someone else may already be using the default port, 8000. Start Claude Science shows how to pass a port. After you start it,
claude-science urlprints both ports. Forward each one with that number on both sides. - If the cluster’s address sends you to one of several login nodes, connect the tunnel to the node where Claude Science is running. Running
hostnameon that node prints its name. - Claude Science needs about 10 GB free in your home folder for its first launch, and more for each environment Claude creates, even if you keep your projects elsewhere.
Approve your own copy of bubblewrap or socat
In version 0.1.71 and later, Claude Science runs a copy of bubblewrap or socat that isn’t in/usr/bin, /usr/local/bin, or /bin only after you approve it. That includes copies from conda, pixi, a cluster module, or your home folder. An approval can’t get around user namespaces that the kernel or AppArmor blocks. Claude Science ignores approvals where your organization manages the network allowlist, and inside a container or sandbox that remaps user accounts.
An approved socat lets Claude Science start, but code that Claude runs has no network access until an administrator installs socat in a system folder. On a new install, Claude Science then can’t set up its starter Python and R environments. It reports “Package downloads are being blocked by network policy” even when the network blocks nothing, and the package mirror it suggests won’t help.
To install both tools with conda and approve them on 0.1.71 and later, install Claude Science, stop it with claude-science stop if it’s running, and run these commands in a terminal:
y at “Approve? [y/N]”. When it prints “Approved bubblewrap” and “Approved socat”, start Claude Science again. Claude Science runs a private copy of each program, so run the second command again whenever you update yours.
On 0.1.70 and earlier, which have no sandbox approve, run only the first command, then the install command. In the approval steps that it prints, give the two paths from the second command, then start Claude Science again.
To approve copies you installed yourself, put the path of each program in the second command, not the path of a launcher. For example, after pixi global install bubblewrap socat, command -v bwrap socat shows launchers in ~/.pixi/bin, and the programs are ~/.pixi/envs/bubblewrap/bin/bwrap and ~/.pixi/envs/socat/bin/socat. If the command says “not approved”, see not approved.
Install Claude Science
claude-science command in ~/.local/bin. If it prints a PATH line at the end, add that line to your shell profile. Then confirm the command works:
Forward the ports from your computer
Set up the tunnel before you start Claude Science: the sign-in link it prints is only valid for about three minutes. By default, the web app listens only on the server’s localhost, so it isn’t exposed to the network. An SSH tunnel makes it reachable from your computer. Claude Science uses two ports: one for the web app (8000) and a separate one for previews of generated HTML, served from its own origin so a previewed page can’t read your session. The preview port defaults to the web app port plus one, so 8001. Forward both. In a terminal on your computer:claude-science url prints both ports. Add a forward for the preview port it prints, with that number on both sides (-L <port>:localhost:<port>).
Start Claude Science
On the server:http://localhost:8000/?nonce=..., right away, and continues setting up its starter Python and R environments; the setup can take a few minutes and about 9 GB of disk. If port 8000 or 8001 is taken on either machine, pass a different port to serve (for example --port 8765) and change the ssh -L forwards to match. Previews then use the next port up, 8766, if it is free.
To run it in the background instead, use claude-science serve --no-browser --detached. claude-science status reports whether it’s running, and claude-science stop stops it.
Sign in
Open the printed link in your computer’s browser. The link is single-use and expires about three minutes after it’s printed; runclaude-science url on the server to print a fresh one at any time. Restarting with claude-science stop then claude-science serve --no-browser also prints a fresh link.
Sign in with your Claude account. If the sign-in redirect can’t find its way back through the tunnel, choose Paste code instead on the sign-in screen. Then complete the setup wizard as described in Get started.
Keep it up to date
claude-science update checks for and installs updates. If your bubblewrap or socat isn’t in a system folder, see Update Claude Science first. See Command line settings for the command reference, including logs and the serve flags.