WEEMS
Use the WEEMS AgentLocal Compute
Docs/Local Compute

Workspace

Local Compute

Step-by-step instructions for setting up WEEMS Local Compute on your own machine — from downloading the setup files to running your first notebook cell locally.

On this page

What local compute does

What local compute does

Local Compute lets WEEMS run your notebook code on your own computer instead of a WEEMS cloud machine. Your WEEMS project stays open in the browser as normal — login, files, and project data all remain online. Only the execution moves to your hardware.

Use it when you want to run code on a specific local GPU, keep data on your own machine, or avoid cloud runtime cost.

You do not need to open the downloaded files in VS Code or any other code editor. Setup is completed using Docker Desktop, your computer's terminal or command prompt, and WEEMS in your browser.

Before you begin

You need:

  • Docker Desktop installed on your computer (download from docker.com)
  • Docker Desktop running — open it and wait until the status bar at the bottom shows the engine is running before continuing
  • WEEMS open in your browser
  • A stable internet connection for the initial runtime download
  • Port 8787 available on your computer (nothing else should be using it)

If Docker is closed or still starting when you begin, later steps will stall even when everything else is correct.

Important

Do not continue past this point until Docker Desktop is fully started and its engine shows a running status.

Step 1 — Open Local Compute in WEEMS

  1. Open your WEEMS project in the browser.
  2. Click the Machine button to open the Machine panel.
  3. Under hardware options, select Use your own computer resources.
  4. The Local Compute setup area will appear.
  5. Choose the runtime that matches your project. If you are unsure, select python-datascience.
  6. Leave the adapter address set to its default value: http://127.0.0.1:8787
  7. In the label field, enter any name you will recognize later, for example: My laptop or Office workstation.
  8. Select your operating system.
  9. Click Download Local Setup Files.

Your browser will download a file named Weems-local-compute.zip.

Video walkthrough
Selecting a runtime, entering a label, choosing your OS, and clicking Download Local Setup Files in the Machine panel.

Step 2 — Extract the downloaded file

  1. Open your Downloads folder.
  2. Locate Weems-local-compute.zip.
  3. Extract it:
    • Windows: right-click the file and choose Extract All, then click Extract.
    • macOS: double-click the file. It extracts automatically.
    • Linux: right-click and choose to extract, or run unzip Weems-local-compute.zip in a terminal.
  4. Open the extracted folder named Weems.

Inside the Weems folder you should see these files:

  • start-local-compute.bat (Windows) or start-local-compute.sh (macOS/Linux)
  • docker-compose.local-compute.yml
  • .env — contains your security token; may be hidden on macOS and Linux because the name starts with a dot
  • local-compute.env — same content as .env, visible fallback copy
  • artifacts.json
  • release.json
  • local-compute-quick-start.md
  • adapter/ — a folder containing the adapter service files

Important

Do not move or delete individual files from the Weems folder before completing setup. The start script depends on all files being present in the same folder.

The extracted Weems folder showing start-local-compute.bat, docker-compose.local-compute.yml, .env, local-compute.env, artifacts.json, release.json, local-compute-quick-start.md, and the adapter subfolder.
Screenshot
The extracted Weems folder. If you are on macOS or Linux, .env may not be visible in Finder or a file manager — this is normal.

Step 3 — Open the Weems folder in a terminal

The start command must be run from inside the Weems folder. Running it from any other location will fail.

  1. Windows — open Command Prompt in the folder

    Open the Weems folder in File Explorer. Click the address bar at the top of the File Explorer window, type cmd, and press Enter. A Command Prompt window will open with its path already set to the Weems folder. Confirm the path shown in the Command Prompt matches the Weems folder before continuing.

  2. Windows — alternatively, use PowerShell

    Right-click inside the Weems folder in File Explorer and choose Open in Terminal or Open PowerShell window here. Confirm the path shown matches the Weems folder.

  3. macOS — open Terminal and navigate to the folder

    Open the Terminal application (search for it with Spotlight or find it in Applications > Utilities). Then type: cd ~/Downloads/Weems and press Enter. If you extracted the Weems folder to a different location, use that path instead.

  4. Linux — open a terminal and navigate to the folder

    Open a terminal application. Then type: cd ~/Downloads/Weems and press Enter. If you extracted the Weems folder to a different location, use that path instead.

Open the weems folder in terminal
Screenshot
Screenshot showing how to open the Weems folder in the file explorer.

Step 4 — Run the start script

Run the command for your operating system. Make sure you are inside the Weems folder before running it.

Windows·Command Prompt
start-local-compute.bat

The script builds the adapter container and starts it. The first run is slower while Docker downloads and builds the required layers. Do not close the terminal while this is still running.

When startup is complete, the terminal will print:

Local adapter is starting on http://127.0.0.1:8787
Running local compute start script in Windows Powershell
Screenshot
Running local compute start script in Windows Powershell and confirming everything went right.

Step 5 — Confirm the adapter is running in Docker

Before returning to WEEMS, confirm the adapter container started successfully.

  1. Open Docker Desktop.
  2. Click Containers in the left sidebar.
  3. Look for a container named weems-local-adapter.
  4. Its status should show as Running.
Docker Desktop Containers tab showing the weems-local-adapter container with a Running status.
Screenshot
Docker Desktop showing the weems-local-adapter container running after the start script completes.

If the container does not appear or shows a failed status, do not continue to the next step. See Troubleshooting below.

Step 6 — Connect WEEMS to your computer

  1. Return to WEEMS in your browser.
  2. Open the Machine panel again.
  3. Confirm the adapter URL is still set to http://127.0.0.1:8787.
  4. Click Connect & Check.

A successful connection shows:

Health: OKNetwork: OKStorage: Pending

Storage shows as Pending because the runtime image has not been downloaded yet. This is expected at this stage.

If Connect & Check fails, see Troubleshooting below before continuing.

Video walkthrough
Clicking Connect & Check in the Machine panel and confirming Health OK, Network OK, and Storage Pending.

Step 7 — Sync the runtime

Click Sync Artifact.

This downloads the Docker runtime image that WEEMS will use to run your notebook. The first download may take several minutes depending on the image size and your internet speed. Do not click Sync again or close Docker while the download is in progress.

When synchronization finishes:

  1. Open Docker Desktop.
  2. Click Images in the left sidebar.
  3. Confirm that the WEEMS runtime image you selected appears in the list.
  4. Return to WEEMS. The Machine panel should now show storage is ready.
Docker Desktop Images tab showing the downloaded WEEMS runtime image.
Screenshot
Confirming the selected runtime image appears under Docker Desktop Images after Sync Artifact completes.

Step 8 — Start the machine

Click Start Machine.

WEEMS will start the runtime on your computer using the adapter and image you prepared. The first start may take longer than later starts while the runtime initializes.

Setup is complete when the Machine panel shows:

RunningHealth: OKNetwork: OKStorage: OK

Do not continue until all four states appear.

WEEMS Machine panel showing Running, Health OK, Network OK, and Storage OK after the local machine starts.
Screenshot
All four states confirm the local runtime is ready.

Step 9 — Verify local execution

Return to your notebook and run a cell:

python
print("WEEMS local compute is running")

Confirm the cell completes successfully and the Machine panel stays in the Running state.

Local Compute is now ready. Keep Docker Desktop running whenever you want to use your local runtime.

Troubleshooting

start-local-compute is not recognized or the file cannot be found

You are running the command from the wrong folder. Open the extracted Weems folder first, then open a terminal inside that folder, and run the command again. On Windows, click the File Explorer address bar, type cmd, and press Enter to open a Command Prompt already pointed at the correct folder.

The weems-local-adapter container does not appear in Docker Desktop

Confirm Docker Desktop is open and its engine status shows running. If Docker was still starting when you ran the script, run the start script again after Docker has fully started.

Docker shows a permission error when the script runs

On macOS and Linux, confirm your user account has permission to run Docker. On Linux, you may need to add your user to the docker group: sudo usermod -aG docker $USER — then log out and back in, and run the script again.

macOS blocks the start script

macOS quarantines downloaded executable files. Run this command first: xattr -d com.apple.quarantine start-local-compute.sh — then run ./start-local-compute.sh. Make sure you are inside the Weems folder when you run both commands.

Port 8787 is already in use

Another application on your computer is using port 8787. Do not change the adapter URL randomly. Close any application that may have started a service on that port, then run the start script again. Contact WEEMS support if you cannot identify what is using the port.

Connect & Check fails after the container is running

Confirm: (1) Docker Desktop is open and the weems-local-adapter container status is Running. (2) The adapter URL in the Machine panel is exactly http://127.0.0.1:8787. (3) A VPN, firewall, security software, or browser extension is not blocking access to localhost on port 8787. Try disabling any active VPN temporarily to test.

Sync Artifact fails or stops partway through

Check your internet connection and confirm Docker is still running. Check Docker Desktop Containers to confirm the weems-local-adapter container is still in a Running state. Wait for any previously started download to fully stop, then click Sync Artifact again.

The runtime image does not appear in Docker Desktop after Sync Artifact

The download may have been interrupted. Click Sync Artifact again and leave the Machine panel open until it completes. Do not close Docker or the browser tab while syncing.

The machine stays on Starting and does not reach Running

Confirm the runtime image appears under Docker Desktop Images. If it is missing, run Sync Artifact again before retrying. If the Machine panel reports a specific failure message, stop the machine, address the reported issue, and start again.

The container was running before but is now gone

The start script uses restart: unless-stopped, so the container restarts automatically when Docker starts — unless you manually stopped it or restarted Docker. Open the Weems folder in a terminal and run the start script again to bring it back.

Collect diagnostics before contacting support

If none of the above resolves the issue, gather this information before reaching out:

  1. Adapter logs: In Docker Desktop, click the weems-local-adapter container, then click Logs. Copy the full output.
  2. Docker status: In Docker Desktop, note the engine status and any error messages shown.
  3. WEEMS error message: Copy the exact error or status text shown in the Machine panel.
  4. Your setup details: operating system and version, Docker Desktop version (visible under Docker Desktop > About Docker Desktop), and the runtime you selected.

Include all of the above when contacting WEEMS support.

Previous

Use the WEEMS Agent

Start a chat, control project changes, and review agent output.