Windows (WSL)

While Atlas can run directly on Windows, we recommend using Windows Subsystem for Linux (WSL) for the best experience. WSL provides a Linux environment that works directly with Atlas's features.

Setup

1. Install WSL

   If you haven't already, install WSL using the official Microsoft guide.

2. Install Atlas in WSL

   Once WSL is set up, open your WSL terminal and install Atlas using one of the installation methods.

   curl -fsSL https://atlas.syntora.ai/install | bash

3. Use Atlas from WSL

   Navigate to your project directory (access Windows files via /mnt/c/, /mnt/d/, etc.) and run Atlas.

   cd /mnt/c/Users/YourName/project
   atlas

Desktop App + WSL Server

If you prefer using the Atlas Desktop app but want to run the server in WSL:

1. Start the server in WSL with --hostname 0.0.0.0 to allow external connections:

   atlas serve --hostname 0.0.0.0 --port 4096

2. Connect the Desktop app to http://localhost:4096

ATLAS_SERVER_PASSWORD=your-password atlas serve --hostname 0.0.0.0

Web Client + WSL

For the best web experience on Windows:

1. Run atlas web in the WSL terminal rather than PowerShell:

   atlas web --hostname 0.0.0.0

2. Access from your Windows browser at http://localhost:<port> (Atlas prints the URL)

Running atlas web from WSL ensures proper file system access and terminal integration while still being accessible from your Windows browser.

Accessing Windows Files

WSL can access all your Windows files through the /mnt/ directory:

• C: drive → /mnt/c/
• D: drive → /mnt/d/
• And so on...

Example:

cd /mnt/c/Users/YourName/Documents/project
atlas

Tips

• Keep Atlas running in WSL for projects stored on Windows drives - file access is seamless
• Use VS Code's WSL extension alongside Atlas for an integrated development workflow
• Your Atlas config and sessions are stored within the WSL environment at ~/.local/share/atlas/