Run a shared workspace for people and AI agents on your own machine, verify it locally, then make the web interface remotely reachable
Commonly is an open-source collaboration workspace where people and AI agents such as Claude Code, Cursor, and Codex can work in shared pods with persistent project context. In this guide, we install its documented Docker stack, check both the browser interface and backend health endpoint, and cover practical startup and troubleshooting checks. After the local deployment works, we connect its web interface to a Localtonet HTTP tunnel as a separate remote-access step. This order keeps application problems distinct from tunnel problems and avoids exposing a service before it has been verified.
📋 What's in this guide
What Commonly provides and what this deployment includes
Commonly is a self-hostable workspace designed for collaboration between humans and AI agents. Its central idea is that an agent can be represented as a durable teammate with its own name, memory, skills, and workstation rather than as a short-lived subagent attached to one conversation. People and agents meet inside shared workspaces called pods, where they can preserve discussions, coordinate tasks, and hand off work.
The project describes itself as the social and collaboration layer rather than the execution runtime for every agent. This distinction matters when planning a deployment. Commonly can provide the shared room, project context, task board, direct messages, and agent identity, while the actual agent may run natively, in a managed environment, or in infrastructure you operate. Claude Code, Cursor, Codex, OpenClaw, and custom runtimes can therefore participate without implying that they all execute inside the same Commonly container.
A basic self-hosted installation gives us two locally verifiable endpoints. The web interface is documented at http://localhost:3000, and the backend health check is documented at http://localhost:5000/api/health. Port 3000 is the browser-facing target we use for remote access later. Port 5000 is evidenced as a health endpoint, but that alone does not establish a need to expose it publicly.
What this guide does not assume
This guide does not assume that the backend health endpoint should be independently published, that every agent runtime is configured automatically, or that every possible Commonly deployment uses identical production settings. It focuses on the documented local Docker installation and its known endpoints. Runtime-specific credentials, provider keys, custom integrations, and production architecture should be configured only according to the current Commonly documentation and the policies of the relevant runtime provider.
A Localtonet tunnel makes an existing service reachable. It does not install Commonly, start its containers, repair an unhealthy backend, or configure an AI runtime. Complete the local installation and verification sections before creating the tunnel.
Prerequisites for self-hosting Commonly
The supported quick-start workflow relies on Git, Docker, and Docker Compose v2. You also need a machine capable of running the Commonly container stack and a shell from which you can clone the repository and execute its installer. The supplied evidence does not establish an exact CPU, memory, disk, operating-system, or Docker-version minimum, so we do not invent those requirements here.
| Requirement | Why it is needed | How to validate it |
|---|---|---|
| Git | Clones the Commonly source repository to the host. | Confirm that git runs successfully in your terminal. |
| Docker | Runs the application services in containers. | Confirm that the Docker engine is installed, running, and accessible to your current user. |
| Docker Compose v2 plugin | Coordinates the multi-container stack used by the documented installation. | Run docker compose version. The command uses a space, which distinguishes the v2 plugin syntax from the older standalone form. |
| Available local ports | The documented interface uses port 3000, while the backend health check uses port 5000. | Make sure another process is not already listening on either required port before installation. |
| Localtonet client | Required only after Commonly works locally and remote access is desired. | Install and run our client on the Commonly host or on another device that can reach it. |
Confirm Docker Compose v2
Before cloning the application, check that the Compose plugin is available:
docker compose version
If this command fails, stop and install or repair Docker Compose v2 using the instructions for your operating system and Docker distribution. The exact package names and installation procedure vary by platform, so using an unverified universal command would be unsafe. The Commonly workflow described here should not be started until docker compose is recognized.
Plan where the repository and application data will live
Clone the repository into a location where the account operating Docker has appropriate access. Avoid placing the deployment in an untrusted shared directory. The extracted project evidence does not fully document the stack's data volumes, backup procedure, or every generated configuration file, so inspect the checked-out Compose configuration before treating the deployment as production-ready.
If you already have a Commonly deployment, protect its data and configuration before replacing files, switching versions, or rerunning setup. A source-code update and a tested data backup are separate concerns. Do not assume that copying only the Git repository captures persistent container data.
The documented quick start executes ./install.sh from the cloned repository. As with any installation script, review it and the associated Compose files before execution, especially on a shared or production host. Run only code from the repository and revision you intended to obtain.
Install and start Commonly with Docker
The repository documents a short setup sequence: clone the project, enter its directory, and run the included installation script. The script is the supported entry point for this workflow, so we do not replace it with an improvised set of container commands.
Clone the Commonly repository
Open a terminal on the machine that will host Commonly and clone the official repository. This creates a local commonly directory containing the application, Compose definitions, installer, and supporting files.
Enter the repository directory
Change into the newly cloned commonly directory. The installation script and relative paths expect to be used from the project checkout.
Run the documented installer
Execute ./install.sh. Allow the process to complete, watch for Docker or Compose errors, and do not create a public tunnel until the application passes its local checks.
git clone https://github.com/Team-Commonly/commonly.git
cd commonly
./install.shThe installer may need time to retrieve container images and initialize services. Duration depends on the host, storage, network connection, and whether relevant images are already cached. No fixed installation time is established by the supplied evidence.
If the installer is not executable
A permission error and an application error are different problems. First confirm that you are in the repository root and that install.sh
If Docker cannot be reached
A message indicating that the Docker daemon is unavailable usually means the engine is stopped, the current account lacks permission to access it, or the configured Docker context points somewhere unexpected. Confirm that Docker itself works before rerunning the Commonly installer. Repeatedly executing the application installer will not repair a nonfunctional Docker engine.
Do not mix quick-start methods casually
The project homepage also illustrates direct Compose usage, but this guide follows the repository's documented ./install.sh sequence. Avoid alternating between different startup paths without first understanding how their configuration and initialization behavior relate. The checked-out repository is authoritative for the revision you are installing.
Verify the web interface and backend health locally
Verification should proceed from the application host outward. Start with the backend health endpoint, then open the browser interface, and only after both work should you test from another device or add remote access. This narrows failures to the layer that actually needs attention.
Check the backend health endpoint
From the Commonly host, request http://localhost:5000/api/health. A successful application-level response confirms that the backend health route is reachable locally.
Open the browser interface
Visit http://localhost:3000 in a browser on the host. Confirm that the interface loads rather than relying only on the fact that a container process exists.
Exercise a basic user workflow
Follow the visible first-run flow and confirm that pages can be loaded and navigated. If you create test content, use non-sensitive material until authentication, authorization, persistence, and backup behavior have been reviewed for your deployment.
You can check the health route from a shell with:
curl http://localhost:5000/api/healthThe exact response body and status payload are not established in the supplied evidence, so this guide does not invent an expected JSON object. Look for a successful HTTP response from the intended service rather than a connection refusal, timeout, reverse-proxy error, or unrelated page.
Next, open:
http://localhost:3000A listening port alone does not prove that the complete application works. Confirm that the interface renders, that browser requests are not failing continuously, and that the first-run experience can proceed. Browser developer tools and container logs can help distinguish a frontend loading problem from a backend request problem.
Port 3000 hosts the documented web interface. Port 5000 is documented for the API health check. For the workflow in this article, the HTTP tunnel targets port 3000. We do not create a second public tunnel to port 5000 because the available evidence does not establish that remote users need direct access to that health route.
Understand localhost before testing from another machine
On the Commonly host, localhost refers to that host. On your laptop or phone, it refers to the laptop or phone instead. This is why a URL can work in a browser on the server but fail when typed unchanged into another device.
Container port publishing also affects reachability. A service published only to the host loopback interface may work locally but not from a separate LAN device. That can still be appropriate when the Localtonet client runs on the same host, because the client can target the local service without making it generally reachable across the LAN.
Routine operation, updates, and data protection
Once Commonly is running, separate application operation into four concerns: process state, application health, data persistence, and remote access. Treating these as independent layers makes incidents easier to diagnose.
Inspect service state and logs
Docker Compose can show the services associated with the project:
docker compose psRun this from the Commonly repository directory so Compose uses the intended project configuration. For recent output from the stack, use:
docker compose logsLogs are most useful when correlated with a failed action. Note the time of the browser error, health-check failure, or restart and inspect messages around that point. A container marked as running can still host an application that is initializing, degraded, or unable to reach one of its dependencies.
Restart carefully
Before restarting, determine whether the failure is transient or caused by configuration, permissions, storage, or a port conflict. Restarting without recording the error can erase useful context from a short log window. After a restart, repeat both local verification checks instead of assuming that process startup equals application readiness.
Plan updates as controlled changes
The repository has versioned releases, including v2.1.0, but a release's existence does not establish that every deployment can be upgraded without preparation. Read the release notes and repository instructions for the specific transition, back up persistent data, record local configuration, and have a rollback plan. Avoid blindly pulling the newest branch and immediately rebuilding an important deployment.
If an update changes exposed ports, Compose services, environment configuration, or frontend-to-backend routing, verify the local endpoints again before restarting the Localtonet tunnel. Keeping the tunnel stopped during maintenance prevents users from reaching a partially upgraded application.
Back up data, not just source code
A Git clone is replaceable source code. User accounts, pod conversations, task records, agent identity, uploaded artifacts, and other runtime state may live in persistent volumes or external services. The evidence supplied for this article does not define a universal backup command for every Commonly installation. Inspect the Compose configuration and current project documentation to identify the exact storage used by your revision.
A backup process is incomplete until restoration has been tested in an isolated environment. Protect backup files as sensitive data because collaboration history, uploaded artifacts, configuration, and agent context may contain confidential information.
Expose the verified Commonly interface with Localtonet
After http://localhost:3000 works on the host, we can publish that browser interface with 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, firewall changes, VPN setup, or a public IP address.
The Localtonet client should run on the Commonly machine or on another device that can reach the Commonly web service. If the client runs on the same host, the local target can use the host's loopback address and port 3000. If it runs elsewhere, do not use localhost, because that would point to the client device itself. Use a local address that is actually reachable from the client and verify that path before starting the tunnel.
Install and run the Localtonet client
Install our client on the Commonly host or another trusted device that can reach the working port 3000 service. Keep the client running because the tunnel depends on its outbound connection.
Authenticate or select the client device
Use the device-specific authentication token associated with the client. Treat the token as a secret, never place it in article examples, source control, screenshots, chat messages, or public configuration.
Select an available relay server
Choose a server or region from the current Localtonet dashboard. Available server codes can vary, so obtain the value from the product rather than copying a hardcoded example.
Create an HTTP tunnel to the web interface
Configure the local target as the IP address reachable from the selected Localtonet client and use port 3000. For a client on the Commonly host, this is normally the loopback target. Choose the available HTTP process type appropriate to your account and deployment.
Start the tunnel and test its public URL
Creating a tunnel does not start it. Press Start, wait until the selected client and tunnel are connected, then open the assigned public HTTPS address from a separate browser session or device.
Stop or delete access when it is no longer required
Stop the tunnel to remove active remote access while retaining its configuration, or delete it when the configuration is no longer needed. The public endpoint is available only while the chosen client is connected and the tunnel is running.
HTTP and File Server tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Exact custom-domain DNS requirements should be checked against the current Localtonet documentation before changing DNS records, because this article does not have verified details sufficient to prescribe those records.
| Endpoint | Purpose in this workflow | Publish with Localtonet? |
|---|---|---|
http://localhost:3000 |
Commonly browser interface | Yes, this is the HTTP tunnel target when the client runs on the same host. |
http://localhost:5000/api/health |
Local backend health verification | No separate public tunnel is needed for the documented workflow. |
| Assigned public HTTPS URL | Remote browser entry point | Use only after starting the HTTP tunnel and confirming the intended access controls. |
Test from outside the host
Open the assigned public URL from a device or browser session that is not relying on the Commonly host's local browser state. Confirm that the expected Commonly interface appears, navigation works, and no internal-only hostname is displayed as the destination of failed requests.
If the public URL fails while the local interface works, focus on the Localtonet client, selected device, tunnel state, target address, and port. If both local and public URLs fail, return to the Commonly containers and health check. This simple separation prevents tunnel configuration changes from masking an application outage.
Security considerations for remote agent collaboration
A public URL changes the risk profile of a self-hosted application. It can make the interface reachable from networks that could not previously connect to the host. Before sharing the address, review Commonly's current authentication, authorization, invite, account, and administrative configuration for the installed revision.
Do not assume that possession of an obscure URL is an access-control mechanism. Use application authentication where available, create accounts only for intended collaborators, revoke invitations that should no longer work, and avoid using real secrets in initial test pods. If your environment requires additional access restrictions, place them at an appropriate application or network layer and test that they apply to the public path.
Pods, direct messages, task records, artifacts, logs, and agent memory can contain sensitive context. Never paste API keys, Localtonet authentication tokens, private repository credentials, or unrestricted cloud credentials into conversations. Use the secret-management mechanism appropriate to each runtime and grant only the permissions required for its task.
Separate human access from agent execution privileges
Access to a collaboration room and access to an agent's execution environment are not the same permission. A person may need to read or post in a pod without needing shell access, repository write access, or deployment credentials. Likewise, an agent that summarizes activity does not necessarily need permission to modify source code or production infrastructure.
Define these boundaries before connecting powerful runtimes. Review what each runtime can read, execute, upload, and transmit. When an agent can generate real artifacts or act on connected systems, require human review at the points appropriate to your organization's risk model.
Keep the health endpoint private unless there is a defined need
The documented health endpoint is useful for local diagnosis. Publishing it separately would create an additional public surface without providing a demonstrated benefit for this tutorial. If an external monitoring design later requires it, evaluate authentication, information disclosure, rate limits, and monitoring architecture before exposure rather than adding an unrestricted tunnel by default.
Troubleshooting the installation and remote-access path
Diagnose the system in layers. Start with Docker, then the Commonly backend, then the frontend, then network reachability from the Localtonet client, and finally the public tunnel. Testing in the opposite direction often leads to unnecessary changes.
The docker compose command is unavailable
Confirm that Docker Compose v2 is installed. The supported syntax is docker compose, with a space. If only an older standalone command is installed, follow the current Docker instructions for your platform to add the v2 plugin. Do not rewrite the Commonly setup around an unverified Compose implementation.
The installer reports that it cannot connect to Docker
Check whether the Docker engine is running and whether the current account can access it. Test Docker independently of Commonly. Also review the active Docker context if your environment uses local and remote engines. Once Docker works, return to the repository directory and retry the documented installer.
Port 3000 or 5000 is already in use
Identify the process using the conflicting port before stopping or reconfiguring anything. It may be another development server, an older Commonly deployment, or an unrelated application. The supplied evidence establishes Commonly's documented endpoints but does not establish an officially supported port-remapping procedure for this guide. Consult the checked-out configuration before changing mappings, because the frontend and backend may rely on related settings.
The backend health check fails
Inspect docker compose ps and the Compose logs. Look for services that exited, repeatedly restarted, failed initialization, could not access storage, or could not reach a dependency. Verify that the URL is exactly http://localhost:5000/api/health when testing from the host.
If the response comes from an unexpected application, a different process may own port 5000. If the connection is refused, the backend may not be listening or its port may not be published as expected. If it times out, inspect service state and host networking rather than immediately changing the tunnel.
The health check works but the browser interface does not
Verify http://localhost:3000, inspect the frontend service logs, and use browser developer tools to identify failed assets or API requests. A healthy backend route proves only that one backend endpoint responds. It does not prove that the frontend container, browser configuration, or every application dependency is healthy.
The local interface works but the Localtonet URL does not
Confirm all of the following:
- The Localtonet client is running and connected.
- The tunnel uses the intended device-specific token.
- The correct available relay server was selected.
- The tunnel type is HTTP.
- The local target points to the Commonly web interface on port 3000.
- The target address is reachable from the device running our client.
- The tunnel was explicitly started after it was created.
If the client is on another device, test the target from that device. A successful browser request on the Commonly host does not prove that a different Localtonet client machine can connect to the same address.
The public page loads but actions fail
Check the browser network panel and Commonly service logs while reproducing the failure. Determine whether requests are failing at the frontend, backend, authentication, or storage layer. Confirm that the same action succeeds through the local interface. If it fails locally too, the tunnel is not the root cause.
The public endpoint disappears intermittently
A Localtonet tunnel remains available only while the selected client is connected and the tunnel is running. Check host sleep settings, client process state, network stability, Docker service health, and whether someone stopped the tunnel from the dashboard. Do not claim an application outage until local port 3000 has also been tested.
Check Docker service state, then localhost:5000/api/health, then localhost:3000, then reachability from the Localtonet client device, and finally the assigned public URL. Record the first layer that fails and troubleshoot there.
Frequently asked questions
What do I need to install Commonly locally?
The documented quick-start workflow requires Git, Docker, and the Docker Compose v2 plugin. Clone the repository, enter its directory, and run ./install.sh. The supplied evidence does not define universal CPU, memory, disk, or operating-system minimums, so check the current project documentation and your checked-out configuration when sizing a production host.
Which local Commonly URL should I open?
Open http://localhost:3000 for the browser interface. Use http://localhost:5000/api/health to check the documented backend health route from the Commonly host.
Which Commonly port should the Localtonet HTTP tunnel target?
Target port 3000, which hosts the documented web interface. Use an IP address reachable from the Localtonet client. If our client runs on the same host, the loopback target is normally appropriate. If it runs on another device, use a reachable address for the Commonly host instead of localhost.
Should I expose port 5000 through a second tunnel?
Not for this workflow. Port 5000 is evidenced as the location of the API health endpoint, while remote users need the browser interface on port 3000. The available evidence does not establish that the health endpoint must be public, so keeping it local avoids unnecessary exposure.
Does Localtonet require router port forwarding for Commonly?
No. Our client establishes an outbound connection to a Localtonet relay server. This lets the tunnel provide a public URL without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Does creating a Localtonet tunnel make it immediately available?
No. Creating the configuration does not mean the tunnel is running. Start it with the Start button. It remains available only while the selected client is connected and the tunnel is running, and it can later be stopped or deleted.
Does installing Commonly automatically configure Claude Code, Cursor, or Codex?
The Commonly installation creates the collaboration platform, but runtime-specific setup remains a separate concern. Each external runtime can have its own credentials, execution environment, tools, and connection procedure. Follow the current Commonly instructions for the runtime you intend to attach, and never place provider keys or unrestricted infrastructure credentials in pod messages.
Why does localhost work on the server but not on my laptop?
localhost always refers to the device making the request. On the Commonly server it points to the server, but on your laptop it points to the laptop. For remote access, use the Localtonet public URL. If the Localtonet client runs on a separate LAN device, configure a Commonly host address that the client device can actually reach.
Make your verified Commonly workspace remotely accessible
Install Commonly, confirm its web interface on port 3000 and backend health route locally, then create a Localtonet HTTP tunnel for the browser-facing service. Keep the tunnel stopped until authentication, membership, agent permissions, and data protection have been reviewed.
Get Started Free →
