Install a local workspace for coding agents, validate its controls, and make remote access conditional on real protection
agentglass brings coding-agent sessions, terminals, worktrees, source changes, pull requests, approval gates, and related development tools into one local workspace. This guide covers the packaged Linux, macOS, and Windows builds as well as the documented Bun source workflow. It also explains state care, hooks, updates, process behavior, local verification, and the security boundary that matters before remote access. Because the available agentglass documentation does not establish browser authentication or public-origin compatibility for source mode, this guide does not recommend publishing the dashboard until you have added and tested a separate protective access layer.
📋 What's in this guide
What agentglass does and why its access boundary matters
agentglass is a self-hosted workspace for coding agents. Claude Code, Codex, Gemini CLI, and OpenCode continue to run on the developer's machine, in local repositories and tmux sessions. agentglass provides a consolidated interface around those tools rather than replacing their command-line programs or provider logins.
The project describes a workspace that can display agent sessions, real terminal panes, tool calls, worktrees, source changes, pull requests, files, Docker resources, listening ports, resource information, and cost or token data. It can create a worktree and branch for a task, start an agent there, and keep parallel jobs from sharing one working directory. Its browser panel can also be driven by an agent through a CLI and MCP server.
Approval gates are especially important to the remote-access decision. A selected tool call can be held until a person allows or denies it. The interface can show the literal command, repository, requesting agent, model, and waiting time. The queue is stored on disk so a crash does not silently permit a queued action.
These are useful development capabilities, but they create a privileged control surface. A user with broad access may be able to read terminal output and source code, inspect repository activity, interact with agents, answer approval requests, or use other enabled workspace functions. That is fundamentally different from exposing a read-only demonstration page.
Platform status, installation commands, and update notes in this article were checked against the current project README and the v0.23.2 release information available on 20 August 2026. Exact asset names and later release behavior can change. Security-sensitive behavior that is not established by the available project documentation is identified as unverified rather than inferred.
Choose the correct installation path
The first decision is whether you want the packaged desktop application or the repository-based development workflow. Both keep application state on your machine, but they do not provide the same documented access surface.
| Installation path | Published format | Documented interface | Important caveat |
|---|---|---|---|
| Linux AppImage | .AppImage |
Packaged desktop application | No browser-accessible port is documented for the packaged application |
| Linux Debian package | .deb |
Installed desktop application | Package compatibility still depends on the local Debian-based system |
| macOS | DMG for Apple silicon or Intel | Packaged desktop application | The current build is unsigned and requires the documented quarantine step on first launch |
| Windows | .exe |
Packaged desktop application | The project says it builds and passes CI but is not verified on physical Windows hardware |
| Source workflow | Git repository and Bun dependencies | http://localhost:4000 |
The documented command is a development workflow, not a documented production service deployment |
The project describes the desktop application as containing its own server with nothing to run in a terminal and no port to open in a browser. It does not publish a connectable browser port for packaged builds. Do not guess a port, scan for an undocumented listener, or assume that packaged builds use localhost:4000. That address belongs to the documented source workflow.
Choose a packaged release when you want the normal desktop experience. Choose source mode when you are developing agentglass itself or need to evaluate the documented HTTP endpoint. The existence of that endpoint does not prove that it is designed or secured for direct public deployment.
Prerequisites
The project lists Git, the Claude Code CLI, and Python 3 as baseline requirements. Running from source also requires Bun because the documented workflow uses bun install and bun run dev. Install and authenticate each underlying agent CLI separately. agentglass does not replace the provider login used by that CLI.
- Git: required by the documented baseline and used to clone and work with repositories.
- Bun: required for the source installation and development command.
- Python 3: required by the documented Claude Code hook installer.
- Claude Code CLI: listed as a baseline requirement by the project.
- A browser: needed to verify source mode at
http://localhost:4000.
Optional dependencies enable related functions. tmux provides live panes and tmux-window integration. GitHub CLI supports the pull-request panel and must be logged in. Docker enables container, image, volume, and log views. The project's Settings ▸ Requirements screen reports what is available and which features stand down when a dependency is missing.
Install the packaged desktop application
Download desktop builds only from the official agentglass release page. Review the release notes and choose the asset that matches your operating system and processor. Asset filenames can vary by release, so identify the format and architecture from the current release rather than copying an old filename.
Linux AppImage
Download the AppImage release asset
Select the current Linux .AppImage file from the official release. Keep it in a location where you can manage application files rather than an untrusted shared directory.
Make the AppImage executable
Use your file manager's executable permission option, or apply the executable bit in a terminal. Substitute the actual downloaded filename if it does not match the wildcard below.
Launch the AppImage
Open the file from the desktop or run it from the terminal. If the operating system reports a runtime or filesystem integration problem, preserve the exact message and check the current project installation notes for that release.
chmod +x ./agentglass*.AppImage
./agentglass*.AppImageLinux Debian package
Download the Debian package
Select the current .deb asset from the official release and confirm that it is intended for your processor architecture.
Open it with the system package installer
Use the graphical package installer supplied by your Debian-based distribution. Review the package identity and requested changes before confirming installation.
Launch agentglass from the application menu
After installation completes, start agentglass as a desktop application. Do not assume that the installed package exposes a browser port.
macOS DMG
Choose the correct macOS build
Download the DMG for Apple silicon or Intel from the official release page. Selecting the build for the wrong processor can prevent the application from launching correctly.
Open the DMG and install the application
Mount the downloaded DMG and place agentglass in the Applications folder using the package's normal installation view.
Remove quarantine once if Gatekeeper reports damage
The project states that its macOS build is currently unsigned. After verifying the official download, run the documented command once against the application in /Applications.
Launch agentglass
Open the application and review Settings ▸ Requirements to see which integrations are available on the Mac.
xattr -dr com.apple.quarantine /Applications/agentglass.appThe command changes how macOS treats the downloaded application. It does not sign or notarize the build. Confirm that the DMG came from the official project release before running it, and reconsider installation if the file's origin cannot be established.
Windows executable
Download the Windows release asset
Obtain the current .exe from the official release page and confirm the publisher context and download origin before opening it.
Run the executable
Follow the prompts presented by the build and Windows. Do not suppress operating-system warnings without first confirming the file's source.
Treat Windows behavior as experimental
As verified on 20 August 2026, the project says the executable builds and passes CI but has not been confirmed on physical Windows hardware. Test the functions you need before relying on it for active work.
After launching any packaged build, open Settings ▸ Requirements. Missing tmux, GitHub CLI, or Docker support should be evaluated against the feature you need rather than treated as a failure of the entire application.
Run agentglass from source
The repository documents a source workflow that clones the project, installs dependencies with Bun, assigns a development state directory, and starts bun run dev. It then identifies http://localhost:4000 as the local endpoint. The separate Python command installs hooks so Claude Code can report activity to agentglass.
The documented source command is bun run dev. The available project evidence does not identify it as a hardened production server, a persistent system service, or a supported public deployment. Expect it to remain attached to its terminal, stop when the process exits, and require an explicit restart after a machine reboot or process failure unless you have independently designed and validated service management.
The inline environment assignment and ~ home-directory path below are for a compatible shell. The verified project material supplied for this revision does not establish an equivalent PowerShell or Command Prompt command, so this guide does not invent one.
Clone the official repository
Clone the project from its official GitHub location. This creates the local repository containing the server, web interface, desktop code, hooks, shared files, and documentation.
Enter the repository
Change into the cloned agentglass directory before running dependency or development scripts.
Install dependencies
Run bun install from the repository root. Resolve dependency, permission, or network errors before attempting to start the service.
Start the development service with an explicit state directory
Use the documented state location and keep the process running. The local web interface should become available at http://localhost:4000.
Install Claude Code reporting hooks if needed
In another terminal at the repository root, run the documented Python installer. Review the script first if hooks are controlled by organizational policy or if you need to know exactly which local configuration files it changes.
git clone https://github.com/SirAllap/agentglass
cd agentglass
bun install
AGENTGLASS_STATE_DIR=~/.local/state/agentglass-dev bun run devWith the development process still running, install the Claude Code reporting hooks if you need that integration:
python3 hooks/install_hooks.pyHook installation is not the same as installing or authenticating every supported agent. Each CLI remains responsible for its provider login, configuration, and runtime process. The verified material documents the installation script above but does not provide a hook-removal command in the evidence available for this revision. Do not guess an uninstall command. Inspect the current hook documentation and installer changes before removing or replacing hooks.
Updates, restarts, state, hooks, and logs
Understand what survives a restart
The development web service exists only while bun run dev is active. Closing its terminal, interrupting the process, rebooting the host, or encountering a development-server failure makes the HTTP endpoint unavailable. A Localtonet tunnel can remain configured, but it cannot produce a healthy agentglass response when the local process is down.
The project separately states that closing agentglass does not inherently terminate agents already running in tmux. This distinction matters during recovery: the dashboard can be unavailable while existing tmux-based agent processes continue working. After restarting agentglass, inspect the restored state and active sessions rather than assuming all underlying work stopped with the interface.
Protect the state directory
The documented source command places development state under ~/.local/state/agentglass-dev. The project says its application data is held in local SQLite storage, but the supplied evidence does not establish a stable database filename or an online-backup procedure.
Treat the complete state directory as sensitive. It can represent workspace state and approval information and should not be published through a file server, committed to a repository, or copied into an untrusted synchronization service. Before making a manual backup, stop agentglass cleanly and copy the complete state directory rather than selecting an assumed database filename. Restore testing should be performed in an isolated environment before depending on a backup.
Pointing multiple active development processes at the same state directory, editing SQLite files while the application is running, or deleting state to solve an unrelated UI problem can cause loss or inconsistency. Stop the process first and preserve a backup before state-level maintenance.
Manage hooks deliberately
The hook installer changes the way Claude Code reports activity to agentglass. Run it only from the trusted repository checkout you intend to use. If you update the repository, inspect current hook documentation and changes before rerunning the installer. If you no longer want the integration, determine the installed changes from the current script or project documentation and remove them through a verified procedure.
Inspect logs where the process writes them
For the source workflow, begin with the terminal running bun run dev. Capture the first error and its surrounding context because later failures may be consequences of the original problem. Remove tokens, repository secrets, private paths, source content, and customer data before sharing output.
Packaged-build log locations are not established in the supplied evidence. Use the application's visible diagnostics and current project instructions rather than assuming that Linux, macOS, and Windows write to the same directory.
Update with the installation method in mind
Release v0.23.2 addressed a specific in-app update-signature problem. Tags from v0.20.0 through v0.23.1 were not signed in the way the updater required, so affected installations could refuse those updates. The v0.23.2 release is signed, and its workflow checks the signature before publishing.
For an installation stuck on an affected older version, the v0.23.2 release notes provide this one-time manual recovery command from a repository clone:
make desktop-installThis is a version-specific recovery procedure, not the general installation command for every platform. From v0.23.2, the release notes state that the update button works again. Review later release notes before applying this workaround to a newer version.
A general source-update sequence is not established by the evidence supplied for this revision. Repository updates can change dependencies, database behavior, hooks, or development scripts. Back up state, read the current release notes, stop the process, and follow the project's current update guidance rather than assuming that pulling code while the server runs is safe.
Verify agentglass locally before considering remote access
Verify a packaged build
- Launch the application and confirm that the main workspace opens without an immediate crash.
- Open Settings ▸ Requirements and inspect the detected integrations.
- Confirm that any agent CLI you intend to use works independently and is authenticated.
- Confirm that the expected repository and tmux sessions appear.
- Test only the enabled features you plan to depend on.
Do not use a packaged desktop test as proof that a browser endpoint exists. The packaged application has its own internal server, but the project explicitly says there is no browser port to open.
Verify the source service
Keep the development process active and open the documented address from a browser on the same machine:
http://localhost:4000Confirm more than initial page rendering. Navigate between several views, inspect the requirements screen, and verify that the expected repository and sessions appear. If you installed hooks, exercise a harmless Claude Code action and confirm that its activity reaches the interface.
Test a representative live feature. For example, observe a terminal or session status while a harmless command runs, or verify that a non-destructive approval test changes state in the interface. The goal is to establish that ongoing updates work locally, not merely that static HTML was returned.
Review the visible data and available authority
- Confirm that only expected repositories, worktrees, files, and sessions are visible.
- Review terminal output for credentials or environment data that should never be shown remotely.
- Use a harmless approval test and verify that denial and allowance behave as expected.
- Review paired-device scopes, such as read, answer, or full, where the Android companion workflow is used.
- Review plugin scopes and revoke plugins that are no longer needed.
- Check whether a user-configured webhook or the Explain function is enabled.
Establish the remote-access security boundary
The project states that agentglass requires no cloud account, uses local SQLite storage, and sends no telemetry. It identifies two opt-in paths by which selected information can leave the machine: a webhook configured by the operator and the Explain function, which sends selected hunks to a model. These local-first properties do not establish browser authentication.
The supplied agentglass documentation describes scoped pairing for the Android companion application and scoped, revocable tokens for plugins. It does not establish that a person opening the source-mode browser endpoint must authenticate, that browser users have roles, or that the source web interface enforces an authorization boundary suitable for internet exposure.
The supplied evidence also does not confirm that all browser APIs, WebSocket connections, event streams, terminal interactions, or other real-time channels are designed to operate through an arbitrary public HTTPS origin. It does not establish required origin headers, trusted-host configuration, secure-cookie behavior, proxy-header handling, or cross-origin restrictions.
A Localtonet HTTP tunnel provides transport reachability to the configured local target. It does not add agentglass user authentication, role-based authorization, or privilege separation. Because browser authentication and public-origin support are not established by the available agentglass documentation, public exposure must remain conditional on a separate protective access layer that you have independently configured and tested for the page, APIs, and all live connections.
The protective layer must reject unauthenticated users before they reach agentglass, preserve the application protocols agentglass actually uses, and enforce the intended user scope. A login page that protects only the first document is insufficient if API calls or real-time connections can be opened directly without the same identity check.
This article cannot name a specific agentglass-native browser protection method because none is verified in the supplied project evidence. It also does not claim that a particular Localtonet security option is available on every subscription or configuration. Confirm current controls in the dashboard and current product documentation before relying on them.
Configure Localtonet only after protection is verified
Once http://localhost:4000 works locally and a separately verified access layer protects the complete application path, you can create a Localtonet HTTP tunnel. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or an inbound firewall change.
Run the Localtonet client on the agentglass host or on another device that can reach the protected local endpoint. If the protective layer listens on a different local address or port, target that protected endpoint rather than routing around it directly to port 4000.
Install and run the Localtonet client
Install our client on the device that can reach the protected agentglass endpoint. Keep the client running and connected while remote access is required.
Authenticate or select the device
Use the device-specific token associated with that client and select the correct device in the dashboard. Never put the token in source code, screenshots, public logs, or this application state directory.
Select an available relay server
Choose a relay server or region currently available in the dashboard. Do not copy a hardcoded server code from an article because availability can vary by account, region, plan, and time.
Create the HTTP tunnel
Set the local IP address and port to the endpoint protected by your verified access layer. Use the process type currently available to your account, such as a generated subdomain, supported custom subdomain, or custom domain.
Start the tunnel
Creating a tunnel does not start it. Press Start, confirm that the selected client and tunnel are connected, and obtain the assigned public HTTPS address.
Test remotely and close access when finished
Perform the authorization and live-feature checks in the next section from a separate network. Stop the tunnel when access is no longer required, or delete it if the configuration will not be reused.
See our HTTP tunnel documentation for the current dashboard workflow. Exact relay values, domain options, and account capabilities should always be taken from the live product rather than assumed from an older tutorial.
Remote access works only while agentglass is running, the protective layer is healthy, the Localtonet client is connected, and the tunnel is started. Saving a tunnel configuration does not make it active.
Test the complete remote path
A rendered page is not enough to validate a privileged, real-time application. Test network reachability, rejection of unauthorized users, authorized browser behavior, API protection, and a representative live operation before treating the deployment as usable.
Recheck the local endpoint
On the host, confirm that the protected local endpoint works and that requests sent directly to an unprotected listener are not unintentionally reachable from other devices.
Attempt access without authorization
Use a private browser session or a separate browser profile with no saved credentials. The request must be rejected or challenged by the protective layer before agentglass data, APIs, terminal streams, or live channels become available.
Authenticate through the intended workflow
Sign in as the intended remote user and verify that the resulting access matches the planned scope. Do not assume that a successful login proves authorization.
Exercise navigation and representative data requests
Open several agentglass views, inspect expected repositories, and confirm that data loads through the public origin. Watch the browser's developer tools for failed API requests, blocked mixed content, repeated authorization failures, or origin errors.
Test a harmless live update
Use a non-destructive terminal or agent action and verify that its changing status reaches the remote browser. This checks more than the initial document and can reveal unsupported WebSocket, event-stream, or other real-time behavior.
Test a safe authorization boundary
Where multiple scopes are part of your protective design, verify that a lower-privileged identity cannot perform a higher-privileged action. Do not use a destructive command as the test case.
Stop the tunnel and confirm closure
Stop the Localtonet tunnel and verify from the remote network that the public endpoint no longer reaches agentglass. Record the tested application version, protection configuration, and tunnel target for future regression checks.
If an unauthenticated browser can retrieve data, connect to a terminal stream, call an API, or observe live updates, stop the tunnel immediately. A protected landing page does not compensate for an unprotected application channel.
Troubleshooting installation, operation, and remote access
The macOS application is reported as damaged
The current macOS build is unsigned. Verify that it came from the official release, place it in /Applications, and run the documented xattr command shown earlier. The command removes quarantine but does not sign or notarize the application.
The Windows build behaves unexpectedly
Record the agentglass version, Windows version, processor architecture, and exact failure. As verified on 20 August 2026, the project describes Windows as building and passing CI but not verified on physical hardware. Do not assume that behavior observed on Linux or macOS will be identical.
bun install fails
Confirm that Bun is installed and available in the current shell, that the terminal is in the repository root, and that dependency sources are reachable. Resolve the first reported installation error before starting the development process.
The source service does not load on localhost:4000
Check that bun run dev is still active and inspect its terminal output. Confirm that it was started from the repository root with the documented state-directory assignment. Check whether another local process already owns port 4000. No alternative agentglass port command is established in the supplied evidence, so this guide does not invent one.
Claude Code activity does not appear
Confirm that Python 3 successfully ran hooks/install_hooks.py from the intended repository checkout. Verify that Claude Code itself is installed, authenticated, and usable independently. Review the installer rather than repeatedly running it if you need to understand or reverse its changes.
An integration is missing
Open Settings ▸ Requirements. tmux, GitHub CLI, and Docker correspond to specific capabilities. For pull requests, GitHub CLI must be installed and logged in. For an agent, verify that its own CLI and login work before investigating agentglass.
The public URL returns an error
Work from the inside out. Verify the local agentglass service, then the protective access layer, the Localtonet client connection, the selected device, the tunnel state, and the configured target. A running tunnel cannot produce a healthy application when the target process is stopped.
The page loads but live information does not update
Compare the same action locally and remotely. If it works on localhost but not through the public origin, inspect the browser console and network panel for failed live connections, origin rejection, authentication failures, or mixed-content errors. Because the available agentglass documentation does not confirm public-origin compatibility, stop the tunnel if you cannot verify every required channel.
Unauthorized users can see any application data
Stop the tunnel immediately. Correct the protective layer so identity checks cover the initial page, API calls, and live channels. Do not rely on changing the URL or creating a less obvious subdomain.
An older build refuses to update
Versions affected by the v0.20.0 through v0.23.1 signature problem may require the one-time make desktop-install recovery from a repository clone. Review the v0.23.2 or later release notes first, back up state, and do not treat this as a universal update command.
Frequently asked questions
Does agentglass replace my coding-agent CLI?
No. Claude Code, Codex, Gemini CLI, and OpenCode remain their normal local tools with their own provider logins. agentglass organizes and interacts with those processes. Agents already running in tmux do not inherently stop when agentglass closes.
Is bun run dev a documented production deployment?
No production-service designation is established by the supplied project evidence. It is the documented development workflow and remains attached to a running process. Do not assume automatic restart, hardening, or long-term service guarantees.
Does the source web interface provide browser authentication?
The supplied documentation does not establish browser-user authentication or authorization for the source endpoint. It documents scoped phone pairing and plugin tokens, but those should not be assumed to protect arbitrary browser access. Do not publish the source interface until a separate protection layer has been verified end to end.
Does a Localtonet HTTP tunnel add application authentication?
No. The tunnel makes the selected local HTTP target reachable through a public endpoint. It does not create agentglass users, assign roles, or reduce application privileges. Authentication and authorization must be supplied and tested separately.
Can I tunnel the packaged desktop application?
Not through a documented browser port. The project says the packaged application has its own internal server and no port to open in a browser. Do not guess or scan for an undocumented listener. The documented localhost:4000 endpoint belongs to source mode.
Does agentglass send repository data to a cloud service?
The project states that agentglass requires no account or cloud service, stores primary data in local SQLite, and sends no telemetry. It documents two opt-in paths that can transmit selected information: a user-configured webhook and the Explain function.
How should I back up source-mode state?
Stop agentglass cleanly and preserve the complete configured state directory. The documented example uses ~/.local/state/agentglass-dev. The supplied evidence does not establish a supported online-backup procedure or stable database filename, so avoid copying an assumed individual file while the application is active.
Does Localtonet require router port forwarding or a public IP?
No. Our client creates an outbound connection to a Localtonet relay server. This provides the configured public endpoint without inbound router port forwarding, a public IP address, VPN setup, or an inbound firewall change.
Should I leave the tunnel running permanently?
Only when persistent remote access is necessary and every application channel is protected and monitored appropriately. For occasional access, stop the tunnel when the task is complete. The tunnel remains available only while its client is connected and the tunnel is running.
Connect a protected agentglass endpoint with Localtonet
Install agentglass, verify its local behavior, protect the complete browser and live-connection path, and test unauthorized rejection before creating an HTTP tunnel to the protected endpoint.
Get Started Free →
