Browse Scient Docs Remote environments

Remote environments

A remote environment lets Scient work inside a project on another computer. This is useful when the data, licensed software, laboratory instruments, compute resources, or organization-managed files live on a workstation or server rather than the computer in front of you.

The important rule is that the work runs where the environment lives. When a remote environment is selected, provider tools, project files, terminals, Git credentials, and other software belong to the remote computer. The desktop app displays and controls that work; it does not silently copy the whole project or run those tools locally.

Connect over SSH

Desktop-managed SSH is the simplest supported remote workflow. Scient uses your existing SSH configuration, starts the matching Scient server on the remote host, and carries the connection through a local encrypted tunnel.

The computer running Scient needs an ssh client and network access to the target. The remote host needs a compatible Node.js version. Configure an SSH key, SSH agent, or host entry in ~/.ssh/config first when possible.

  1. Open Settings → Environments and choose Add environment.
  2. Choose SSH.
  3. Select a suggested host, or enter its host name, optional user, and optional port.
  4. Review any host-key or password prompt and connect.

Packaged desktop releases install and start the matching Scient server release on the remote host. Scient runs only that exact release, never a server command already installed on the host or a package from npm. Saved SSH environments reconnect through the same target. If the route, credentials, Node runtime, or remote launch fails, Scient keeps the environment disconnected and reports the problem instead of switching to another machine.

If Scient started the remote server for this SSH connection, disconnecting stops that process. A compatible server that was already running is left running.

Where remote data lives

On the remote host, Scient keeps its server data in ~/.scient-next, the same folder Scient desktop uses on that computer. If the host also runs Scient desktop, an SSH connection uses that computer’s own Scient server. Scient never connects to a server that uses the ~/.t3 folder, which other apps share.

Earlier Scient versions kept remote data in ~/.t3. The first connection from a newer version copies that data to ~/.scient-next once, when ~/.scient-next does not exist yet and the data in ~/.t3 was written by Scient. The copy holds threads, settings, attachments, and the server’s credentials. Worktrees, projects, and scratch folders stay where they are and keep working from there; installed tools and runtimes download again when needed. The data in ~/.t3 stays as it was so an older Scient version can still use it, but the two folders do not share later changes. A ~/.t3 that another app wrote, or that Scient cannot read, is never changed, and Scient starts with an empty ~/.scient-next.

The copy runs before the server starts, so that first connection can take longer; the copy itself may run for up to 15 minutes. While it runs, a saved connection reports that Scient is still preparing the host and keeps retrying; it connects once the copy finishes, or shows the copy’s error if it fails. Before copying, Scient stops the server it started on ~/.t3 for this connection, once it has confirmed that process is that server. The connection fails without copying anything if another older Scient server is still using ~/.t3, if Scient cannot confirm which process its old server is, or if ~/.t3/userdata contains a symbolic link, which the copy would share with the old folder. Disconnect older Scient apps from the host or stop that server, then reconnect. To start fresh instead of copying, create an empty ~/.scient-next folder on the host before connecting.

Scient Connect

Scient Connect reaches your computers from anywhere without opening ports or setting up a VPN. Sign in once, turn it on for a computer, and that computer appears in Scient on your other devices and at app.scientfactory.com in any browser.

  1. On the computer to share, open Settings → Sharing & access and sign in to Scient Connect with Google, Microsoft, GitHub or email.
  2. Turn on Scient Connect for that environment. The first time, Scient asks to download the relay client (cloudflared) and checks it against a pinned checksum before installing it.
  3. On another device, sign in with the same account. The computer is listed under Scient Connect; select it to connect.

On a server without a screen, run scient connect and open the printed link on any device to sign in. scient connect status shows whether other devices can reach the computer. When a connection fails, see Scient Connect troubleshooting.

How it works: Scient’s relay at relay.scientfactory.com keeps your account’s list of computers and creates one private Cloudflare tunnel per computer, at an address under scientusercontent.com. Your threads, files and terminals travel directly between your device and that tunnel; the relay does not carry them. Cloudflare decrypts tunnel traffic at its edge before passing it on, as with any site behind Cloudflare. A computer that stays offline for a while loses its tunnel and gets a new one, at the same address, when it comes back.

Each account can link a limited number of computers at once. Settings → Sharing & access shows how many are in use; remove one you no longer use to free a place.

A computer is reachable only while Scient runs on it: the desktop app, or scient serve on a server (see headless server). This is the same on macOS, Windows and Linux; Scient does not install a background service.

Direct and private-network access

Advanced deployments can run a separately managed headless server and connect through a reachable endpoint. A private network such as Tailscale can make the server reachable without exposing it directly to the public internet.

Keep these responsibilities separate:

  • how you run the server decides how it starts and updates;
  • SSH, a direct endpoint, or a private network decides how the client reaches it; and
  • a pairing credential decides what that client is allowed to do.

Endpoint behavior follows the actual address:

  • an HTTPS/WSS endpoint works from clients allowed to reach it;
  • a non-loopback HTTP endpoint can be used for direct LAN pairing; and
  • 127.0.0.1 is reachable only from the server computer.

For a server you start in a terminal, scient serve --lan accepts connections from your local network and tailnet, but not from public addresses. A pairing code is then all that keeps other devices on those networks out.

Prefer SSH forwarding or a correctly secured private HTTPS endpoint. Do not expose an unauthenticated Scient server port to the public internet.

On a computer with the desktop app, you can open the printed scient://pair app link instead. The desktop app asks you to confirm the server address, then adds it.

Reach one machine several ways

A machine can have more than one route: LAN, Tailscale, another VPN, a public URL, or SSH. Tailscale shares its 100.64.0.0/10 address range with other VPNs such as Cloudflare WARP, so an address in that range shows as VPN unless the machine confirms it is on Tailscale. To add a route, choose Add route in the machine’s route list. A pairing link for a saved machine is refused when it comes from an address that machine does not have yet; add that address with Add route instead. Pairing again over an address the machine already has still works. A new route is placed by speed, in that order, and you can reorder routes at any time.

While connected through a paired address, Scient also learns the machine’s current LAN and Tailscale addresses and adds them as routes, so pairing once is enough to use the LAN at home. When the machine’s LAN address changes, for example after it joins another Wi-Fi network, the learned route follows it. The machine must allow network access for its LAN address to be learned: Network access in the desktop app, or scient serve --lan for a server in a terminal. You can reorder a learned route, but not remove it; it goes away with the route it was learned through, or when the machine stops reporting that address.

Scient connects over the first route that answers. Away from home, a LAN address that does not answer is checked briefly and skipped. It is only tried again, after the other routes, if none of them connect. While connected over a later route, Scient checks the earlier ones when your network changes, when you return to the app, and every minute, and moves back as soon as one works.

On web and desktop, select the route count under the machine’s name in Settings → Environments to see its routes. Drag a route to change the order, or remove it. On mobile, open the machine under Settings → Environments and choose Edit.

Open Permissions next to Routes in web or desktop, or Your permissions in the mobile route details, to see what your current connection can do on that environment. For a remote environment, this is in its route details. Permissions shown there apply only to the route marked In use; other routes are not checked. Separately paired routes have separate sessions and may grant different permissions.

Balance new threads across machines

Auto balance is off by default. On web and desktop, enable it in Settings → Environments → Load balancing to automatically choose a machine for new threads in projects grouped across connected environments. The section appears once two or more machines are switched on. Each machine starts at Normal. Choose Prefer to favor it when it has CPU and memory available, Less often to reduce its share, or Manual only to exclude it from automatic selection. These are preferences, not fixed traffic percentages. Preferences are saved separately in each client.

The composer checks eligible machines when choosing a draft’s environment, then keeps that choice stable. Choose Auto balance again to check current resources, or choose a specific machine to override it. Choosing a branch or worktree also keeps the draft on that machine. Existing threads stay where they started. If resource checks are unavailable or all eligible machines are full, choose a machine manually to continue. Mobile keeps its manual environment selection.

Tailscale HTTPS

When the desktop app detects Tailscale, Settings → Sharing & access can show its Tailnet IP, MagicDNS name, and an HTTPS MagicDNS endpoint. Tailscale HTTPS is off until you explicitly enable it. Turning it on asks Tailscale Serve to proxy private HTTPS traffic to the local Scient backend; turning it off removes that mapping.

This is an endpoint option, not a separate kind of Scient environment. LAN, custom HTTPS, Tailscale, and SSH connections all use the same environment and pairing model.

Headless server

For a separately managed server, use the exact Scient release archive and SCIENT_SERVER_PACKAGE variable described in Run a Scient server without the desktop app. Do not substitute a package name for the release URL. For example, a Tailnet-only server can be started with:

npx --yes --allow-scripts=node-pty@1.1.0,msgpackr-extract@3.0.4 --package="$SCIENT_SERVER_PACKAGE" scient serve --host "$(tailscale ip -4)"

Use the same package command with scient serve --help for the complete options. To ask the server to manage Tailscale Serve directly, use --tailscale-serve; advanced users can add --tailscale-serve-port 8443 for another HTTPS port. The command prints the address and temporary pairing information needed by a client.

Pair a client safely

In Settings → Sharing & access, create a time-limited pairing link or code with only the read and write permissions that client needs. Share it only with the intended device, and revoke unused links or sessions from the same page.

Pairing codes and share links are available only in the client that created them, while its Sharing & access page remains open. After leaving or reloading that page, create a new link to share. Other clients can see a link’s name, scopes, and expiry, and can revoke it if they have access-management permission.

The default endpoint controls the QR code and primary copy action. You can change it in the expanded endpoint list. The preference follows the endpoint type rather than a particular IP address.

Treat a pairing link like a temporary password:

  • do not paste it into a public issue, repository, or shared transcript;
  • choose the smallest useful permission set;
  • revoke it after an unexpected disclosure; and
  • remove saved access from a device you no longer control.

Connecting successfully does not give every operation unlimited access. The server continues to enforce the selected scopes and the conversation’s permission mode.

Antigravity sign-in on a remote environment

Antigravity runs and saves its Google credentials on the selected environment. You can start setup from a remote Scient client without signing in over SSH.

Google returns to a 127.0.0.1 address on the device running the browser. If that browser is on another computer, the final page may fail to load; this is expected. Copy the complete return address, including its query string, and paste it into the same Antigravity setup flow where sign-in started. Do not change the address to the server hostname or paste it into a conversation or bug report. See Antigravity for the complete flow.

Keep versions aligned

When the remote server version differs from the desktop client, Scient offers the appropriate action from the update control at the bottom of the sidebar and in Settings → Environments. Use that exact action or copied command; see Update Scient. Changing the package or version can produce an incompatible server.

The hosted app at app.scientfactory.com follows the latest Scient release, so keep computers you open there updated.

If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that Scient launched; a server that was already running is left alone.

Each desktop app keeps one session on the host for its SSH connection and reuses it when it reconnects. Revoke sessions you no longer use in Settings → Sharing & access on the host, or on a headless host with scient auth session list and scient auth session revoke <id>. A desktop that can still sign in over SSH pairs again on its next connect.

For Antigravity’s Google callback on a remote host, see remote sign-in.

Use the desktop app only for remote environments

If this computer should only control work running elsewhere, turn off Local environment in Settings → Environments. Scient restarts without a local server: local providers and terminals stop, WSL backends stay off, and other devices can no longer connect to this computer. Existing local projects, history, and saved connections are kept.

Browser on a remote environment

Browser tabs belong to the environment, so you and your agents see the same tabs from any device. The desktop app shows its own environment’s tabs directly. Every other device, and the desktop app for other environments, streams them from the host. Agents keep using them while no device is connected, and localhost addresses reach servers on the host.

The first tab downloads a headless Chrome, about 120 MB, into the Scient home. It is the same browser HTML renders use, so a host downloads it only once. Some Linux hosts need setup before it can start.

Agent tabs have separate storage and share a Chromium process. Take control before typing into an agent’s tab, then release control when you want the agent to continue. Read-only connections can watch without changing the page.

While you have control, the tab works with your device: text the page copies or cuts goes to your clipboard, a file picker on the page opens your device’s picker, and a finished download is offered for you to save. Popups such as sign-in windows open as their own tabs. Downloads stay on the host until the tab closes. Audio does not play on your device.

On a phone, tap the floating preview’s corner dot to show its controls, then Pop into separate window to keep watching in picture-in-picture over other apps.

Local servers

The browser lists a local server once it has a Preview URL: set one on the project action that starts the server. Scient checks that address and opens it as written, including HTTPS addresses and specific paths. It does not send web requests to other ports, even ones your terminals and agents opened, because a process may use a non-web protocol. To open any other local server, enter its URL in the browser.

Browser host setup

macOS, Windows, and Linux desktops run the browser as is. Some Linux hosts need one-time setup: Ubuntu 23.10 and later block the sandbox the browser runs in, and minimal images and containers lack libraries it loads. When that happens, the server says so at startup, and browser tabs and HTML previews show the command to run on the host:

sudo scient browser setup

The server shows the exact line for the installation that runs it, usually with the full path of the desktop app’s scient launcher or of the Node runtime and server it runs from, so it works even where scient is not on your PATH. It keeps your PATH when Node is installed only for your user. It allows Chrome’s sandbox with an AppArmor profile and installs any missing libraries and system fonts with apt; pages that load without text can mean the host has no fonts. It is safe to run again. Without sudo, it only reports what it would change.

The browser runs in Chrome’s sandbox by default. Chrome cannot start that sandbox as root. If your Scient server runs as root, run it as a nonroot user to keep sandboxing enabled. scient browser setup does not fix this root restriction.

If you need to run as root, or cannot enable the sandbox on your host, set T3CODE_SERVER_BROWSER_SANDBOX=0 in the Scient server’s environment and restart the server. This disables Chrome’s sandbox. For a manual launch:

T3CODE_SERVER_BROWSER_SANDBOX=0 npx --yes --allow-scripts=node-pty@1.1.0,msgpackr-extract@3.0.4 --package="$SCIENT_SERVER_PACKAGE" scient serve

If you run the server under your own systemd unit, add Environment=T3CODE_SERVER_BROWSER_SANDBOX=0 under [Service] in its configuration, run sudo systemctl daemon-reload, then restart that unit. Setting the variable in an agent’s terminal does not change the environment of an already running Scient server.

Connect an outside agent

Claude Code, Codex, ChatGPT and other agents Scient did not start can drive threads on an environment through its MCP server. See outside agents for setup.

Link two machines, such as your laptop and a VPS, and agents on one can work on the other: launch, message, wait on and stop its threads, answer their questions, and manage its queues, projects and scheduled tasks.

Linked environments is a beta. Turn it on for both machines in Settings → Labs; on mobile, Settings → Labs lists each connected machine. While it is off on either machine, agents start nothing over a link between them. A task already running on the other machine still finishes, and if that machine has it off, its result arrives once it is back on.

On the machine you will work from, open Settings → Environments → Linked environments, choose Link, and pick the other machine or enter its address. The list holds the machines this app knows. If this app is connected to that machine with a session that manages access there, it makes the pairing code itself; otherwise paste one from that machine’s Settings → Sharing & access. From a terminal, use scient environment link <address> --pairing-code <code> --access <mode>.

You can also ask an agent to link a machine by name, such as “delegate this to my vps”. It shows a card in the thread where you pick the machine the same way and the access, then approve.

  • The access you pick is the most agents from this machine may do there. An agent also never gets more there than its own mode here.
  • Threads a link starts are marked From and this machine’s name there.
  • A full-access link works there like that machine’s own agents. Below full access, the link’s agents can change only threads it started, not that machine’s own threads, projects or settings, and they skip its project setup scripts.
  • The link shows up in that machine’s Settings → Sharing & access like any outside agent. Revoke it there to end it. Forget on this machine only removes it here.
  • Links last 30 days. Link again with a new pairing code to renew one.

An agent can also hand a task to a linked machine with delegate_task: it runs there as an ordinary thread, in the project with the same repository (or the one target.projectId names), and this thread wakes with its result when it ends, as for any delegated task. It keeps following the task across restarts. If the other machine revokes the link, or the link is removed here, the task fails with that reason.

Manage or revoke access

Turn Local environment back on in the same place to restore the previous local environment.

Removing a saved remote environment from Settings → Environments forgets it on this device only. A computer linked through Scient Connect stays on your account until you turn Scient Connect off on it, or remove it from your account in Settings → Sharing & access; that also deletes its tunnel.

When the app connects to more than one environment, choose one at the top of the page. A desktop app with Local environment off can manage a background service on the same machine this way.

A session with an open connection stays listed after its access credential expires.

To choose a token’s permissions, pass --scope once for each scope you want:

scient pair --scope orchestration:read --scope relay:read

The selected scopes replace the default permissions. The same option works with scient auth pairing create and scient auth session issue; each command’s --help lists the available scopes. Without --scope, pairing tokens and issued bearer sessions get every permission, including managing access. A terminal or a full-access agent on the host can reach that as well, so a client that should not manage access also needs to go without terminal:operate and orchestration:operate.

To change an existing client’s permissions, create a fresh pairing link with the scopes it needs. In a browser opened directly on the environment, open that link to replace the browser’s current grant. For mobile or a saved remote environment in web or desktop, use Add Environment with the fresh link or code; pairing the same environment replaces its saved grant. Reconnecting alone does not change permissions.

Grouping checkouts does not combine their permissions. Shared project settings require orchestration:operate on every member environment; actions on one checkout use that checkout’s permissions.

source-control:write covers direct Git and pull request changes made from the client: pushing, switching or creating branches, cloning, and removing worktrees. It does not restrict what a task does. Starting a task in a new worktree still creates that branch and worktree with orchestration:operate, and the agent it runs can use Git however the environment allows.

Settings changes, provider management, environment maintenance, access management, and relay management can each be granted separately. New pairings without --scope include all of them. Existing clients keep the permissions they paired with and can stay connected after an update, but newly separated features may require pairing again with the permissions they need. Older clients may show controls that the server denies. Create a fresh pairing link to change a client’s permissions.

filesystem:read allows browsing host files, opening workspace files, and viewing local changes. Add filesystem:write to allow editing files or saving plans to the workspace. These scopes control direct file access from the client.

Treat pairing URLs and authorization codes as passwords. Do not include them in screenshots, logs, or bug reports.