Set Up Cezar and Access Its Cockpit with Localtonet

How Cezar and Localtonet fit together

Cezar is an open-source orchestration environment for AI coding agents. Its cockpit lets you queue tasks, inspect runs, answer questions, review changes, and coordinate supported agent CLIs. It can run work in parallel Git worktrees, apply checks, and leave changes at a review gate rather than merging them automatically.

Cezar does not replace the underlying agent. Claude Code performs the coding work using its own authentication, permissions, account access, and usage allowance. The official Cezar site describes the local workflow as requiring no Cezar account or database. That is an installation characteristic, not evidence that its browser interface has authentication suitable for public access.

The canonical Cezar repository is the project to consult when checking behavior against your installed release. This tutorial deliberately covers Claude Code only. Cezar supports other agents, including Codex, OpenCode, and Pi, but their installation and authentication are outside this workflow.

With Localtonet, our client establishes an outbound connection to a relay server. An HTTP tunnel forwards requests from a public HTTPS URL to an HTTP service reachable from that client. You do not need inbound router port forwarding, a public IP address, firewall changes, or VPN setup for this tunneling workflow. Organizational network policies and authorization requirements still apply.

Prepare the local environment

The Cezar site currently lists macOS, Linux, and WSL2 with Node.js 20 or newer for its command-line experience. It also offers desktop packages for macOS, Windows, and Linux, but those are a separate installation path. The commands below use a macOS, Linux, or WSL shell throughout.

• Node.js 20 or newer: use a currently supported release satisfying Cezar's minimum, rather than choosing an obsolete runtime simply because it meets the version floor.
• npm and npx: verify the package runner is installed in the same environment as Node.js.
• Git and an existing repository: choose a non-production project you are authorized to let an agent inspect and modify.
• Claude Code access: have an eligible Claude subscription, a Claude Console account, or organization-provided access through a supported provider.
• A local browser: use it to verify Cezar before considering remote connectivity.
• Outbound connectivity: package installation, agent authentication, and agent requests require access to their respective services.

Install and check Node.js

Obtain Node.js through the official Node.js download and installation page, selecting the instructions for your operating system and architecture. On macOS, an official installer is an option; on Linux or WSL2, use the Linux installation method appropriate to that environment. Avoid combining a Windows runtime with Linux-side project tools.

node --version
npm --version
npx --version
git --version

Each command should print a version. The active Node.js major version must be at least 20. If an executable is missing, finish its installation and reopen the terminal before proceeding. When multiple runtimes are installed, the version printed in this terminal is the one relevant to the upcoming Cezar launch.

Establish a clean project baseline

cd /path/to/your/project
pwd
git status

Replace the example path with your repository. Account for existing changes by committing, stashing, or documenting them according to your team's workflow. Run the project's normal dependency installation and tests when practical, and record known failures. Otherwise, a pre-existing build failure may later be misattributed to an agent.

On WSL2, keep Node.js, Claude Code, and Cezar in the same Linux environment. Do not assume an executable installed in Windows is available to a Linux process. The Localtonet client will also need to reach the service from its own network context, which becomes important during tunnel configuration.

Install, authenticate, and validate Claude Code

The official Claude Code quickstart documents the following native installer for macOS, Linux, and WSL. Run it only if downloading and executing the vendor's installer is permitted in your environment:

curl -fsSL https://claude.ai/install.sh | bash

The installer may show no progress while downloading. When it finishes, open a new terminal and verify the executable:

claude --version

A successful installation prints a version followed by the Claude Code name. If your shell cannot find it, resolve the installation or PATH problem before starting Cezar. The official quickstart includes alternative installation methods for environments where the native installer is unsuitable.

Start your first session

cd /path/to/your/project
claude

On first use, follow the login prompts. For a Claude subscription or Console account, complete authentication in your browser. Enterprise provider or gateway access depends on configuration supplied by your organization. If an existing ANTHROPIC_API_KEY is present and you approve its use, Claude Code can use that credential instead of prompting for the subscription login. Confirm you are using the intended account and billing route.

The interactive prompt displays the version, current model, and working directory. Enter /help to check that the session responds. If you need to switch accounts or reauthenticate, use /login inside the running session.

Validate an actual agent request

Ask a small inspection question, such as:

What does this project do? Summarize its structure without modifying files.

Review permission prompts and the resulting answer. This checks more than whether the executable starts: it exercises authentication, account access, and repository visibility. Do not approve unexpected commands merely to complete the test. Exit the interactive session using its normal controls when finished.

The native Claude Code installation automatically updates in the background. Record its version when diagnosing a Cezar compatibility issue. Consult the Claude Code settings reference for permission and managed-policy settings rather than disabling protections to make automation run.

Start Cezar in the intended repository

The Cezar site documents npx cezar-run as its command-line entry point. No separate global Cezar installation is required for this path.

cd /path/to/your/project
git status

npx cezar-run

The Cezar v0.18.0 release notes explicitly describe onboarding that signs users in to an agent, helps select or create a project, and connects GitHub. This is release-specific evidence, not a promise that every installation presents identical screens. Signing into an agent or GitHub is also not proof that incoming cockpit visitors must authenticate.

For reproducing that release, its published installation command is:

npx cezar-run@0.18.0

Use version pinning deliberately, not as a recommendation to remain on an older release indefinitely. The unpinned command is not a reproducibility guarantee: npm resolution, local packages, and cached execution can affect what runs. Record the actual version displayed by the application or startup output. Do not assume every invocation automatically upgrades an existing installation.

Verify the cockpit locally before adding another layer

Confirm the HTTP service

Open the local address reported by Cezar in a browser on its host. If startup confirms port 4321, test:

http://localhost:4321

For a same-environment tunnel target, also test the explicit loopback address:

curl -I http://127.0.0.1:4321

Substitute the actual port when different. A response confirms an HTTP listener, but does not prove that the correct application is running or that every route works. Some applications do not support HEAD requests, so a method error from this command is not automatically a startup failure. The browser remains the important functional check.

Do not infer the bind address from a URL containing “localhost.” An application may print that URL while listening on additional interfaces. Check the installed application's configuration or your operating system's listening-socket tools before treating the deployment as loopback-only.

Confirm the project and agent

Verify that the cockpit refers to the repository you intended to manage. Check the path before dispatching work. If Claude Code worked directly but is unavailable in Cezar, compare the user account, shell PATH, and operating environment used to launch each process.

Run a small inspection request through the cockpit. Review its output and any permission questions. This validates the connection among the cockpit, orchestration process, agent, and repository without requiring a broad modification.

Exercise the review loop

Next, use a small reversible task on a development branch. Inspect the diff and run normal project checks. Cezar documents workflow checks where exit status zero means success and failures return to the agent for retry. Changes wait at a review gate, and Cezar does not merge them automatically. Preserve that boundary rather than interpreting a green check as permission to merge without inspection.

Operate Cezar safely after installation

Start with conservative parallelism

Cezar supports workspace-level and project-level parallel limits. Extra work waits in a queue. Choose a small limit initially, then observe CPU, memory, disk use, test-suite behavior, and agent account limits. Multiple worktrees can still share host resources, credentials, and external development services.

The Cezar site describes queues that survive restarts and a memory ceiling that pauses heavy runs. Neither feature makes abrupt shutdown harmless. Inspect active work before maintenance, and check run states afterward rather than assuming every interrupted process resumes identically.

Keep review gates and least privilege

Review generated files, dependency changes, configuration edits, and shell commands as carefully as application code. Keep branch protections and required CI checks. Give integrations only the repository access they need, and avoid broadly privileged credentials on the agent host.

Inspect queued or blocked tasks before restarting anything. A run may be waiting for capacity, an answer, a check result, or an account usage reset. Restarting the server is not the appropriate first response to normal waiting states.

Understand process lifecycle

In this terminal-based workflow, keep the Cezar process and host running. Sleeping the machine, closing its terminal, losing power, or terminating the process can interrupt operation. A Localtonet tunnel does not keep the laptop awake or install Cezar as a system service.

Before shutting down, stop remote access first, then review active tasks and stop Cezar using its normal controls. For a foreground terminal process, interruption commonly uses Ctrl+C; confirm the process has exited instead of assuming closing the browser stopped it.

Update deliberately

Record Cezar, Claude Code, and Node.js versions when establishing a working baseline. Review release notes before changing a long-running environment, particularly where authentication or stored credentials are involved. For example, v0.18.0 notes keychain changes that older binaries cannot read. Do not assume downgrading is always a safe rollback.

Evaluate public access before configuring Localtonet

A cockpit can expose repository content, agent conversations, tool execution, and privileged actions. HTTPS protects the browser's transport to the public endpoint; it does not determine who is allowed to view projects or start tasks. A private-looking URL, an agent login, and a GitHub connection are not substitutes for incoming user authentication.

If your organization supplies an authenticated access gateway, the tunnel target must be the protected entry point, not a route that bypasses it. That gateway's setup is outside the verified instructions here. Confirm protection for application APIs and streaming connections as well as the initial HTML page. If you cannot establish that boundary, continue locally or evaluate a documented private-access deployment.

Localtonet client installation scope

Our HTTP tunnel documentation is the maintained entry point for the client and HTTP workflow, and the Localtonet documentation covers supported tunnel families. Install and run the client appropriate to the operating system and architecture of the device that can reach your protected service.

The evidence available for this revision does not include a verified direct client download URL, platform-specific installer commands, or the exact current HTTP form sequence. We therefore do not supply guessed download paths, executable names, or installation flags. This section describes the supported configuration lifecycle, not a claim to reproduce every current dashboard screen. Use the current official client installation instructions before proceeding.

On macOS or Linux, the simplest network arrangement is a client in the same host environment as the service. On WSL2, do not assume a Windows-side client reaches a Linux-side listener through its own 127.0.0.1. Verify reachability from the actual client environment. Loopback always refers to the environment making the connection, not automatically to the one containing the repository.

Supported tunnel lifecycle, only after the security gate passes

HTTP Process Type options include Random Sub Domain, Custom Sub Domain, and Custom Domain, subject to current availability. Each provides a public HTTPS address. Exact custom-domain DNS requirements must come from current documentation; a custom hostname does not add application authentication.

Public verification must test denial as well as success

• From a signed-out browser, confirm that repository data and agent controls are unavailable.
• Confirm that unauthenticated requests cannot use application APIs, not just that the landing page displays a login form.
• With an authorized account, confirm access is limited to the intended resources and actions.
• Test a harmless inspection request and normal cockpit updates, not only the initial page load.
• If any access-control check fails, stop the tunnel immediately and investigate locally.

For remote access to work, the application must remain healthy, the selected Localtonet client must stay connected, and the tunnel must remain running. None of these conditions replaces the security gate above.

Troubleshoot from the inside out

The package runner is unavailable or startup fails

Repeat node --version, npm --version, and npx --version in the current terminal. Resolve missing executables or an unsupported runtime before retrying. Distinguish a shell command-not-found error from a package download, registry, or application startup error. Read the actual message rather than reinstalling every component.

The cockpit does not load

Check that Cezar is still running and use the address reported by startup. Do not assume port 4321 if the installed release reports otherwise. Check for an occupied port or a terminated process. No supported alternate-port flag is established by the evidence here, so do not guess one or terminate an unrelated process blindly.

If localhost works but 127.0.0.1 does not, investigate whether the listener is bound only to IPv6 loopback or another interface. Configure the tunnel only after the actual target is reachable from the client environment.

Cezar cannot find or use Claude Code

Run claude --version and start an interactive session from the same shell and user account. A successful version check does not validate credentials. Complete a small request directly; if necessary, reauthenticate with /login. Keep account and usage-limit problems separate from executable discovery.

The wrong repository appears

Check pwd and git status, then inspect the project path in the cockpit. Resolve the mismatch before assigning tasks. Do not infer the project solely from a familiar repository name when multiple checkouts exist.

Local access works but the public route fails

First retest the protected local entry point from the Localtonet client's environment. Then check the selected device, connected client, running tunnel, target IP and port, and currently assigned URL. A client in another container, VM, or WSL environment may interpret loopback differently.

If the page loads but updates or tasks fail, test those functions locally and inspect application errors. Do not disable origin checks, authentication, or other security controls as a troubleshooting shortcut.

Remote access unexpectedly disappears

Check whether the host slept, Cezar exited, the client disconnected, or the tunnel stopped. The public route cannot keep the underlying application alive. Avoid repeatedly restarting agent runs until you understand whether the problem is connectivity or task execution.

A task remains queued or paused

Inspect parallel capacity, pending questions, failed checks, and account limits. Cezar's queue is not proof of a fault. Review the individual run state before restarting services, and preserve relevant logs without sharing tokens, source secrets, or private repository details.

Choose between local operation and an Ubuntu VPS

Cezar's site documents this Ubuntu VPS installer entry point:

npx cezar-run server-install --platform ubuntu-vps

The site states that this path sets up HTTPS, a login, and a system service. Those properties are specific to the server installer and must not be assumed for the plain local command. A VPS is generally the better operational fit when work must continue after your laptop sleeps.

This is an alternative to evaluate, not a complete VPS deployment tutorial. The available evidence does not establish every supported Ubuntu version, installer prompt, DNS requirement, or administrative prerequisite. Review the current Cezar instructions before running it on a server, and test login, updates, backups, and recovery as part of that deployment.

A Localtonet tunnel is not normally needed simply to duplicate the VPS installer's documented public access. If public exposure is unnecessary, evaluate private networking instead. Our VPN Manager is a separate private mesh feature; ordinary HTTP tunneling is not a VPN. Private networking still requires sensible application permissions and trusted devices.

Frequently asked questions