Windows WSL deployment of local Agent tutorial: Ollama, Codex OSS and permission control

When deploying local Agents on Windows, the most worry-free structure is usually not to scatter the model service, Docker, terminal and coding tools in Windows, WSL and multiple virtual environments, but to put them into the same WSL2 Ubuntu distribution:

1
2
3
4
5
6

Windows
└─ WSL2 Ubuntu
   ├─ Ollama：本地模型服务
   ├─ 本地模型：聊天、代码、Embedding
   ├─ Codex OSS：Agent 客户端
   └─ 项目目录：代码、Git、测试命令

In this way, Ollama and Agent communicate directly through localhost in WSL, and the path, permissions and logs are all in the Linux environment. The Windows side can continue to access the project using Windows Terminal, VS Code Remote WSL, or Explorer.

Let’s talk about the conclusion first

The minimum available route is:

1
2
3
4
5
6

安装 WSL2 Ubuntu
-> 在 Ubuntu 安装 Ollama 和一个小模型
-> 在 Ubuntu 内验证 ollama run
-> 用 codex --oss --local-provider ollama 启动 Agent
-> 先执行只读任务
-> 再逐步允许修改、测试和工具调用

Don’t give the local Agent full permissions from the beginning, and don’t go after the largest model first. It is more important to first use a model verification process that can run stably than to deal with complex agents, remote ports, and multi-agent orchestration first.

Step 1: Install WSL2 and Ubuntu

Execute in Administrator PowerShell on Windows:

1

wsl --install

After rebooting, Ubuntu will be installed by default. When you open Ubuntu for the first time, follow the prompts to create a Linux username and password.

Confirm that the distribution uses WSL2:

1

wsl -l -v

If the old distribution is still version 1, you can convert:

1

wsl --set-version Ubuntu 2

Enter Ubuntu:

1

wsl

Most of the subsequent commands are executed in the Ubuntu terminal, not PowerShell.

Step 2: Prepare Ubuntu basic environment

After entering WSL, update the system first:

1
2
3

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git ca-certificates

Confirm environment:

1
2
3

uname -a
pwd
git --version

It is recommended that the project be placed in the Linux file system, for example:

1
2

mkdir -p ~/projects
cd ~/projects

Do not run high-frequency Git, Node.js, Python virtual environments and large-scale dependencies under /mnt/c/.... Cross-file system access can be slower on some development tasks and more likely to encounter permissions and file listening differences. When you need to open a project from Windows, you can use VS Code’s Remote WSL feature.

Step 3: Install and verify Ollama within WSL

Follow the Ollama Linux installation method:

1

curl -fsSL https://ollama.com/install.sh | sh

First start the service in the current terminal:

1

ollama serve

Open another WSL terminal, download and test a model:

1
2

ollama pull qwen3:8b
ollama run qwen3:8b

Model selection must be determined by your GPU memory or CPU/memory. When there is no available GPU, use a smaller model to verify the process first; don’t mistake “large model files can be downloaded” for “this machine can perform smooth inference”.

Confirm service and model status:

1
2

ollama ls
ollama ps

If ollama run itself cannot output stably, solve the problem of model, video memory, driver or memory first, and then connect to Agent.

Step 4: Check if the WSL GPU is actually available

When you have an NVIDIA GPU, execute within WSL:

1

nvidia-smi

Being able to show the graphics card doesn’t mean Ollama has used the GPU, but it at least proves that WSL sees the driver. After starting the model, execute:

1
2

ollama ps
nvidia-smi

Observe whether the model uses GPU and whether the video memory increases.

If nvidia-smi does not exist or an error is reported, first check the NVIDIA driver, WSL version and GPU support of Windows. Do not rush to install the desktop Linux driver repeatedly in Ubuntu. WSL’s GPU support has its own driver link.

Step 5: Let Codex use local Ollama

Codex offers OSS mode with the option of Ollama or LM Studio as the local provider. Once Codex is installed and runnable within WSL, go into your project directory:

1

cd ~/projects/your-project

It is recommended to start with read-only permissions for the first time:

1

codex --oss --local-provider ollama --sandbox read-only

First give a task that does not modify the file:

1

阅读当前仓库的 README 和目录结构，说明启动、测试和构建命令。不要修改任何文件。

After confirming that the local model can understand the warehouse and the answer is stable, use the workspace write permission as needed. Don’t skip Git, testing, and permissions just because it’s a local model.

If you want to use Ollama as the default local provider, add ~/.codex/config.toml in the user-level Codex configuration:

1

oss_provider = "ollama"

Then use the following command:

1

codex --oss

Note that provider-related configuration should be placed in user-level configuration, not .codex/config.toml in the project. The project configuration should not covertly change your machine’s model provider.

Step 6: Enable systemd when resident services are required

New installations of WSL Ubuntu usually already use systemd by default. First check:

1

systemctl status

If systemd is not enabled in the current distribution, edit:

1

sudo nano /etc/wsl.conf

join in:

1
2

[boot]
systemd=true

Then go back to Windows PowerShell:

1

wsl --shutdown

Check systemctl status again after re-entering Ubuntu.

Whether to make Ollama a resident service depends on the installation method and whether you need a backend API. When you first start learning, it is easiest to keep a ollama serve terminal to see the logs; after it is confirmed to be stable, use systemd to manage the service.

Paths, ports and APIs within WSL

By default, the Ollama service uses:

1

http://localhost:11434

If the agent, script, and Ollama are all in the same WSL distribution, this local address will be used first, and there is no need to open the LAN port first.

Test API:

1

curl http://localhost:11434/api/tags

When it needs to be called in Windows programs, mobile phones or other devices on the local area network, the network exposure method, reverse proxy and authentication must be designed separately. Do not map exposed local model ports directly to the public network.

Recommended resource ratings

A larger model does not mean a more reliable Agent. For local Agents, command execution stability, context, tool calling capabilities, and task splitting methods also affect the results.

The easiest trap to step into

1. Windows and WSL each run a set of Ollama

This will make it difficult for you to tell which service the Agent is actually connected to. For initial deployment, it is recommended to run only one set of Ollama within WSL, and all testing is completed on the same WSL terminal.

2. Run all development tasks in /mnt/c

Accessible, but may not be ideal depending on installation, file listening, Git performance, and Linux permissions behavior. Prioritize active projects in ~/projects.

3. The local model allows writing files from the beginning

First use --sandbox read-only to verify whether the model understands the task. Once you enter the modification phase, you should also let it explain the plan before checking diffs, running tests, and using Git to retain fallback points.

4. There is no authentication after the port is opened.

Once a local API is allowed LAN access, it is no longer just a “service on your own computer.” At a minimum limit firewall sources and add authentication and HTTPS at the reverse proxy layer if necessary.

5. Thinking that if the installation is successful, it will automatically run in the background.

The foreground process exits when WSL is closed or the distribution is stopped. When long-term APIs are required, first confirm systemd, service status, and Windows/WSL operating policies.

Summarize

Windows WSL deploys local Agents. The most reliable first version is:

1
2
3
4
5

WSL2 Ubuntu
-> Ollama 跑通小模型
-> Codex OSS 模式只读分析仓库
-> Git 和测试验证
-> 再增加写权限、服务常驻和局域网 API

Keeping the model, agent, and code in the same WSL environment can reduce path, port, and permission issues by more than half. Wait until the minimal process is stable before considering Docker, multi-model routing, RAG, or remote access.

refer to:

• Microsoft Learn: Install WSL
• Microsoft Learn: WSL systemd
• Ollama Linux Documentation
• Codex OSS Local Provider
• Local large model API for Codex usage tutorial