Self-Host Qwen Code with qwen serve and Localtonet

What this self-hosted Qwen Code workflow provides

Qwen Code is an agentic coding tool that runs on a computer with access to a selected project. Its normal interactive mode starts with the qwen command and presents a terminal interface. The same project also documents headless execution for scripts, integrations for supported editors, SDKs, desktop applications, and an experimental daemon mode.

The daemon starts with qwen serve. It provides an HTTP service using the Agent Client Protocol, or ACP, and streams events with Server-Sent Events, commonly abbreviated as SSE. Instead of every interface starting a separate Qwen Code subprocess, multiple compatible clients can connect to one daemon and participate in a shared session. The official daemon documentation describes clients such as IDE integrations, web interfaces, CI scripts, and custom command-line applications.

A built-in Web Shell is served from the root of the daemon. The documented default URL is http://127.0.0.1:4170/. The Web Shell and API use the same origin, so this basic workflow does not require a second application port. The default loopback address is deliberately local: software on the same machine can connect, while another device cannot connect directly through the LAN or internet.

Localtonet does not install, configure, or authenticate Qwen Code for you. The Qwen Code daemon remains on your machine and retains access to the workspace and model provider you configure. Our role begins after the service works locally: the Localtonet client forwards requests from a public HTTP endpoint to the local daemon.

This separation is useful for diagnosis. If the Web Shell does not load at 127.0.0.1:4170, the problem is local and should be fixed before a tunnel is created. If local access works but the public address does not, the investigation can focus on the Localtonet client, tunnel state, selected device, and target configuration.

Prerequisites and decisions to make first

Prepare the host, project, model access, and security boundary before installation. The host must remain powered on while Qwen Code is needed remotely. The Qwen Code daemon, the Localtonet client, and the tunnel must all be running for the public address to work.

Choose the machine and workspace

Install Qwen Code on the computer that holds, or is allowed to reach, the project you want the agent to work with. Run it under an operating-system account with only the filesystem and command permissions that the workflow needs. Avoid starting an internet-accessible coding agent under an unnecessarily privileged administrator or root account.

Use a dedicated test repository for the first setup. Commit or back up important work before allowing an agent to modify it. Version control makes proposed file changes easier to inspect and reverse, but it does not protect untracked secrets, external systems, databases, or commands with side effects.

Choose an installation path

Qwen Code officially documents three normal installation paths. The standalone installer is the quickest path on Linux, macOS, and Windows. npm is appropriate when Node.js 22 or later is already installed and available on PATH. Homebrew is supported on macOS and Linux.

Prepare model-provider access

Qwen Code requires a model provider. On first launch, its provider menu can offer Alibaba ModelStudio choices, supported third-party providers, and a custom provider for a local server, proxy, or otherwise unsupported provider. The correct endpoint, model, API key, account permissions, and billing arrangement depend on the provider you choose.

Keep provider credentials out of terminal history, screenshots, source control, Qwen instruction files, and this article's example commands. The provider credential is separate from a Qwen daemon bearer token and separate again from a Localtonet device token. Each credential has a different purpose and should be stored and rotated independently.

Prepare Localtonet

You also need a Localtonet account and the Localtonet client on the device that will run, or can locally reach, Qwen Code. A Localtonet device authentication token identifies that client. Tokens are device-specific and should never be pasted into documentation, issue reports, chat transcripts, or shared configuration examples.

Relay server and region choices can vary. Select an available value from the current Localtonet dashboard rather than copying a server code from an old tutorial. Plan availability and specific options can also vary, so use the choices displayed for your account.

Install Qwen Code using an official method

Choose exactly one normal installation path. Running multiple installers is unnecessary and can leave different qwen executables on PATH. If a previous installation exists, first identify which executable your shell resolves and follow the project's current upgrade or uninstall guidance for that installation type.

Option 1: standalone installer on Linux or macOS

In a terminal, run the official standalone installation command:

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

This downloads the installation script and passes it to the shell. Piping a remote script directly into a shell is convenient, but it means you are trusting its current contents. In controlled environments, review the script and your organization's software-installation policy before executing it.

Option 2: standalone installer on Windows

Open PowerShell and run the documented Windows command:

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Restart PowerShell or your terminal application after installation if the qwen command is not found. This lets updated environment variables and PATH entries take effect.

Option 3: install globally with npm

Confirm that Node.js 22 or later and npm are already available, then install the latest published Qwen Code package:

node --version
npm --version
npm install -g @qwen-code/qwen-code@latest

The output from node --version must represent Node.js 22 or later. If the global install succeeds but the command remains unavailable, the usual issue is that npm's global executable directory is not on the current shell's PATH. Correct the npm environment rather than repeatedly installing the package.

Option 4: install with Homebrew

On macOS or Linux with a working Homebrew installation, run:

brew install qwen-code

Whichever method you choose, close and reopen the terminal if necessary. Then ask the executable for its help output:

qwen --help

A rendered help response confirms that the shell can resolve and execute Qwen Code. It does not yet prove that a provider is configured, the project is trusted, or the daemon can start.

Configure authentication and verify the interactive agent

Before starting a network service, verify the simpler terminal workflow. This isolates installation, provider authentication, project access, and basic model operation from HTTP and tunneling concerns.

The core commands for this check are:

cd /path/to/your-project
qwen

Replace the example project path with a real local path. Once the interface opens, use:

/auth

Successful verification means the application launches, the intended provider is configured, a harmless prompt receives a response, and the agent is operating in the intended workspace. If any of these checks fail, fix them before moving on to qwen serve.

Start and verify the qwen serve daemon locally

Start the daemon from the workspace you want to expose:

cd /path/to/your-project
qwen serve

The official daemon documentation identifies http://127.0.0.1:4170/ as the default Web Shell address. Open that exact URL in a browser on the same computer:

http://127.0.0.1:4170/

You can also ask Qwen Code to open the Web Shell automatically:

qwen serve --open

For an API-only daemon without the built-in Web Shell, the documented switch is:

qwen serve --no-web

The API-only mode is not the best choice for the browser-focused workflow in this guide. Use it only when a compatible client will connect directly to the daemon protocol and you have verified that client's requirements.

Local verification checklist

Confirm all of the following while still testing through the loopback address:

• The daemon process remains running and does not exit with a configuration or provider error.
• The browser can load the Web Shell from 127.0.0.1:4170.
• A harmless text prompt receives a streamed response.
• The session points to the intended workspace, not the user's home directory or another repository.
• Permission requests are visible and can be accepted or rejected as expected.
• Stopping the daemon makes the local page unavailable, proving that the test is reaching this process rather than a cached or unrelated service.

The loopback default is helpful when Localtonet runs on the same computer. Our client can target 127.0.0.1 without changing Qwen Code to listen on every network interface. This keeps the daemon unavailable directly from the LAN while the public access path is handled through the outbound tunnel.

Multiple clients and session behavior

Under the daemon's documented default single-session scope, clients that target the same workspace collaborate on the same ACP session. That can include shared conversation state, file diffs, and permission prompts. When the agent asks to use a tool, all connected clients may see the request, and the first response wins.

This behavior is useful for intentional pair work, but it also means the service should not be treated as a multi-tenant application. A collaborator may observe or affect the same agent session. Establish who is allowed to answer permission prompts and avoid connecting untrusted users to the same daemon.

Secure Qwen Code before public exposure

The default loopback deployment does not need authentication for purely local access. That assumption changes when requests can arrive through a public URL. Qwen Code documents bring-your-own bearer-token support through the QWEN_SERVER_TOKEN environment variable, as well as the --token and --require-auth controls.

Generate a strong, unique secret using an approved password manager or secret-management system. Set it in the daemon process environment without committing it to the repository. The exact secret injection method depends on your operating system, shell, service manager, and deployment policy, so this guide intentionally does not place a reusable credential in a command.

Require authentication for shared-host or tunneled use. Then verify that your intended browser interface or ACP client can supply the bearer token correctly before relying on it remotely. Do not assume that a client supports authentication merely because it can connect to an unauthenticated loopback daemon.

Use a narrow workspace

Run the daemon from a dedicated project directory and avoid registering broad directories unless the workflow genuinely requires them. The official daemon supports repeated --workspace options for multiple isolated workspace runtimes under one listener, with the first workspace acting as the primary default. More workspaces increase the material reachable through one service, so add them deliberately.

Keep approval controls conservative

A model response is not a substitute for human authorization. Commands can delete files, change dependencies, contact external systems, or expose data through tool output. Review requested actions and diffs before approving them. Be especially careful when more than one client is connected because the first permission response determines the result.

Protect model cost and side-effect endpoints

Some daemon operations can trigger additional model calls. The official documentation specifically warns that session recap requests are pure-cost side queries and historically lacked a per-route rate limit in the documented v1 behavior. Authentication reduces the risk of an unknown client repeatedly consuming model tokens, but trusted clients should also avoid uncontrolled request loops.

Separate secrets by purpose

Expose the verified daemon with a Localtonet HTTP tunnel

Once Qwen Code works at http://127.0.0.1:4170/ and daemon authentication has been verified, add remote connectivity as a separate layer. HTTP is the appropriate Localtonet tunnel family because the daemon serves a browser interface and ACP traffic over HTTP with SSE.

The Localtonet client establishes an outbound connection to a Localtonet relay server. This means you do not need inbound router port forwarding, a public IP address, firewall changes, or VPN setup for this tunnel workflow. The assigned public HTTPS address forwards to the local Qwen Code target while the selected client is connected and the tunnel is running.

For the current dashboard workflow and available options, consult our Localtonet HTTP tunnel documentation. The exact relay choices, domain options, and plan-dependent capabilities visible to you should take precedence over screenshots or values from older tutorials.

Validate the complete request path

Test from outside the Qwen Code host after the tunnel starts. A useful validation sequence is:

1. Open the Localtonet public HTTPS address.
2. Verify that an unauthenticated request cannot use the daemon.
3. Authenticate with the Qwen daemon's supported client flow.
4. Confirm that the expected project or workspace is selected.
5. Send a read-only prompt and observe the streamed response.
6. Trigger no destructive tools during the connectivity test.
7. Disconnect the remote client and confirm that the local daemon remains healthy.
8. Stop the Localtonet tunnel and verify that the public address no longer reaches the service.

A tunnel is available only while the selected Localtonet client is connected and the tunnel is running. Qwen Code must also remain running. If any one of those three components stops, remote access ends.

Routine operation and troubleshooting

A safe startup sequence

Use the same order each time so failures are easy to locate:

1. Start the host and confirm network access.
2. Open the intended project directory.
3. Load the Qwen daemon bearer token through your approved secret mechanism.
4. Start qwen serve.
5. Verify http://127.0.0.1:4170/ locally.
6. Start the Localtonet client and confirm that the correct device is connected.
7. Start the existing HTTP tunnel.
8. Test authentication and a harmless prompt through the public HTTPS address.

Reverse the exposure-related portion when finishing. Stop the tunnel first so new remote requests cannot arrive, then stop Qwen Code. If access is no longer needed, delete the tunnel rather than leaving an unused configuration available for accidental restart.

The qwen command is not found

Restart the terminal after using the standalone installer. If npm was used, verify Node.js is version 22 or later and determine whether npm's global executable location is on PATH. If Homebrew was used, verify that the Homebrew executable directory is available to the current shell. Avoid installing through every method because that can hide the underlying path problem.

The interactive CLI opens, but prompts fail

Run /auth and confirm that the intended provider is selected. Check provider credentials, account access, configured model availability, network reachability, and provider-specific quotas or billing. Do not debug this through Localtonet because a failure in the local interactive CLI is not caused by the tunnel.

The daemon does not start

Read the terminal error before changing settings. Confirm that the installed Qwen Code release supports qwen serve, that provider configuration works in interactive mode, and that port 4170 is not already occupied. This article does not invent a port-changing flag because the supplied evidence only establishes the documented default address and port. Use the daemon documentation for your installed version if a different port is required.

The Web Shell does not load locally

Make sure the daemon process is still running and test the exact default URL, including http, loopback address, and port:

http://127.0.0.1:4170/

If you started the daemon with --no-web, the browser Web Shell is intentionally disabled. Restart without that flag for this workflow. Browser extensions, local proxies, and endpoint-security software can also affect a local request, so compare browser behavior with a direct local HTTP test tool available in your environment.

Local access works, but the public URL does not

Confirm that the Localtonet client is connected under the device selected by the tunnel. Verify that the tunnel is actually started, not merely created. Check that the tunnel family is HTTP and that the target remains 127.0.0.1:4170 when our client runs on the Qwen host. Also confirm that the assigned public address is the current address shown in the dashboard.

If Localtonet runs on another computer, 127.0.0.1 points to that other computer rather than the Qwen host. Move our client to the Qwen host for the loopback design used here. Do not expose Qwen Code broadly on the LAN by guessing undocumented bind options.

The page loads, but streaming stalls or reconnects

The daemon uses SSE, which keeps an HTTP response open while events are delivered. Test the local Web Shell first to distinguish a Qwen process or provider problem from the remote path. Then compare a different browser or network. The Qwen daemon documents reconnect support using Last-Event-ID within its replay window, but a specific client still needs to implement compatible reconnection behavior.

Do not claim a performance or uptime guarantee for either component. Actual responsiveness depends on the Qwen host, selected model provider, client, network path, active session, and available relay option.

Authentication works locally but not remotely

Confirm that the remote interface knows how to provide the Qwen bearer token. A browser opening a URL cannot automatically infer a secret stored on the host. Client authentication behavior can vary by Qwen Code release and interface, so verify it against the current daemon documentation. Never work around an incompatible client by disabling daemon authentication on a public tunnel.

The wrong project appears

Stop the public tunnel before investigating. Confirm the directory from which Qwen Code was started and review any registered workspace options. The first workspace is documented as the primary default for requests that omit a working directory. Restart the daemon from the intended project, verify locally, and only then restart the tunnel.

Multiple users interfere with permission prompts

This follows the documented first-responder permission model. Every connected client can see a permission request, and the first answer wins. Limit access to a coordinated trusted group, agree on who controls approvals, or use separate daemon instances and workspaces where your installed release and operating model support that design. Do not present one shared session as isolation between mutually untrusted users.

Remote access stopped unexpectedly

Check the three independent lifecycle states: the Qwen daemon process, the Localtonet client connection, and the tunnel's running state. A tunnel configuration can still exist while stopped. Likewise, a running tunnel cannot reach a daemon that has exited. Host sleep, terminal closure, provider failures, and normal client shutdown can interrupt the workflow.

Logging and incident response

Avoid collecting secrets in screenshots or copied logs. If a model-provider key, Qwen bearer token, or Localtonet device token may have been exposed, stop the tunnel, terminate the daemon, and rotate the affected credential through its owning system. A Localtonet device token does not replace the Qwen daemon token, and rotating one does not rotate the others.

Frequently asked questions