Run the Petdex development stack locally, verify its web gallery, and make the working preview available over a public HTTPS address
Petdex is an open-source gallery, CLI, and desktop ecosystem for animated coding-agent companions. This guide focuses specifically on its supported local full-stack development workflow: clone the repository, install its Bun dependencies, start the Docker or Podman environment, and verify the Next.js interface at http://localhost:3000. After the application works locally, we explain how to connect that HTTP endpoint to Localtonet for temporary remote access. The documented Petdex workflow is intended for development, so it should not be treated as a production deployment configuration.
📋 What's in this guide
What the Petdex full stack includes
Petdex describes itself as three related experiences. Its public web gallery lets the community browse, submit, review, and showcase animated pets. Its command-line tool installs pets on a user's machine and supports catalog operations such as listing and submitting pets. Its desktop application displays a floating companion that can react to supported coding-agent activity.
This article is not a tutorial for installing one pet with npx petdex install, and it is not a desktop application setup guide. Instead, it covers the repository's developer workflow for running the Petdex web application and its supporting services locally. That distinction matters because the prerequisites, commands, and expected result are different.
The repository identifies the web stack as Next.js 16, React 19, Tailwind, Drizzle, PostgreSQL, Redis, Clerk, and R2. The codebase includes the public gallery, individual pet pages, collections, submission interfaces, CLI-facing endpoints, a public manifest endpoint, and administrative review surfaces. Petdex also maintains its SQL migration history through Drizzle.
Petdex documents two local development paths. The supported full-stack path uses bun run dev:docker with Docker or Podman. The other path runs bun run dev against real services and requires a populated .env.local; the project identifies that route as being for maintainers. For a normal contributor or evaluator, the Docker or Podman full-stack path is therefore the appropriate starting point.
http://localhost:3000, giving you a concrete HTTP endpoint to test before any remote sharing is introduced.
dev:docker workflow supports Docker or Podman and is intended to bring up the local development environment without requiring the maintainer-only real-service configuration.
bun install to install dependencies and bun run dev:docker to start the supported full-stack workflow.
Installing a Petdex pet, installing Petdex Desktop, and developing the Petdex website are separate workflows. If your only goal is to use an existing pet, you do not need to clone and run the full web repository. The full-stack procedure below is for contributors, developers, integrators, and reviewers who need a local Petdex web instance.
Prerequisites for running Petdex locally
Prepare the development machine before cloning the repository. The official command sequence establishes four direct requirements: Git for cloning, Bun for dependency management and scripts, Docker or Podman for the supported full-stack environment, and a browser for local verification.
The available project evidence does not specify exact minimum versions for Git, Bun, Docker, or Podman for this full-stack repository workflow. We therefore do not recommend inventing version numbers. Use a currently supported release of your chosen tools, confirm that each executable is available in your terminal, and consult the current repository if a future Petdex revision adds explicit version constraints.
| Requirement | Why it is needed | What to verify |
|---|---|---|
| Git | Downloads the Petdex repository and its tracked project files. | Confirm the git command is available in the terminal where you will run the setup. |
| Bun | Installs repository dependencies and runs the documented development script. | Confirm the bun command is available. No repository-specific Bun version is established by the supplied evidence. |
| Docker or Podman | Provides the container runtime used by the supported local full-stack workflow. | Confirm the selected runtime is installed, running, and usable by your current account. |
| Available local port 3000 | Petdex instructs developers to open the web interface on this port. | Make sure another process is not already occupying localhost:3000. |
| Web browser | Loads the local Next.js interface and provides the first functional verification. | Use a browser on the development machine to open http://localhost:3000. |
| Localtonet client, optional | Creates the outbound connection used for remote access after local verification succeeds. | Install and run it only on a device that can reach the Petdex HTTP service. |
Check the container runtime before starting
Docker or Podman must be operational, not merely installed. A stopped container service, insufficient permissions, or a runtime that cannot create containers will prevent bun run dev:docker from completing. Resolve runtime-level errors before changing Petdex source files or dependency settings.
The repository describes an approximately 30-second warm-up for the full-stack command. Treat that as an orientation rather than a performance guarantee. Initial image downloads, dependency caches, machine resources, disk speed, and network conditions can make the first startup take longer.
Choose a suitable development machine
Run Localtonet on the same machine as Petdex or on another device that can reach the Petdex local IP address and port. Running both on the same machine is usually the simplest arrangement because the tunnel target can remain the loopback service. If the Localtonet client is on a different machine, verify ordinary private-network connectivity first. A tunnel cannot repair a local routing or firewall problem between the client device and the target service.
First load Petdex directly through http://localhost:3000. Remote tunneling adds another networking layer, so enabling it before local verification makes failures harder to isolate. It can also expose an application whose development routes, data, or authentication behavior you have not yet reviewed.
Install and start the Petdex full stack
Run the following workflow from a terminal on the development machine. These steps preserve the order documented by the Petdex repository. Do not substitute the maintainer-only bun run dev path unless you already have the required real-service configuration and understand the project's current environment requirements.
Clone the Petdex repository
Download the project from its official public repository:
git clone https://github.com/crafter-station/petdex.gitEnter the project directory
Change the terminal's working directory to the newly cloned repository:
cd petdexInstall the project dependencies
Use Bun to install the dependency set represented by the repository:
bun installAllow the installation to finish before starting the development environment. If it fails, preserve the original error output and resolve that dependency or network problem rather than proceeding with a partially installed tree.
Start the supported containerized full stack
Launch the Docker or Podman development workflow with the repository's documented script:
bun run dev:dockerKeep this process running while you test the application. The repository notes an approximate 30-second warm-up, although a first run can take longer while the runtime obtains and initializes required resources.
Open the local Petdex interface
After startup settles, open the documented local endpoint in a browser:
http://localhost:3000Do not create a public tunnel until this address responds locally and the interface behaves as expected.
Why the command uses the Docker name when Podman is supported
Petdex names the script dev:docker, but its repository explicitly describes Docker or Podman as supported setup choices for this local full-stack path. Use the script name exactly as documented regardless of which of those supported runtimes is installed.
Do not silently switch to the real-services workflow
The alternative bun run dev command requires .env.local to be filled and is described as being for maintainers. The available documentation does not provide a general-purpose set of safe placeholder values for those real services. Clerk issuers, storage endpoints, database access, and similar configuration must not be guessed.
If dev:docker does not meet a specialized integration requirement, obtain the current maintainer-approved environment configuration before using the real-services route. Avoid copying secrets into shell history, commits, screenshots, tunnel URLs, or support messages.
Verify the local Petdex service before sharing it
A successful terminal launch is not, by itself, enough to prove that the application is ready. Verification should cover network reachability, browser rendering, route behavior relevant to your task, and repeated requests while you watch the development output.
Confirm the root page responds
Visit http://localhost:3000 from the same machine. The browser should reach the Petdex interface rather than displaying a connection refusal, an unrelated service, or a generic proxy page. If another application appears, port 3000 may have been occupied before Petdex started.
Check more than the first HTML response
A Next.js page can return its initial document while later asset requests or server-side operations fail. Confirm that styling and client-side behavior load, navigate through the specific pages involved in your work, and review the terminal for recurring errors. If your change affects a route, API operation, database-backed view, or static asset, test that exact path locally.
Petdex's codebase contains public gallery pages, individual pet routes, collections, community and submission experiences, public manifest behavior, CLI endpoints, and administrative surfaces. You do not need to test every area for a small change, but you should test every surface you intend to show remotely.
Distinguish expected warm-up from a failure
During startup, supporting services may not become ready at exactly the same instant as the browser server. If the page fails during the initial warm-up, wait for the development output to settle and try again. If the same error continues, treat it as a real configuration or service problem rather than repeatedly refreshing indefinitely.
If http://localhost:3000 works but the future public URL does not, focus on the Localtonet client, tunnel state, selected device, relay selection, and local target. If the localhost address itself fails, keep troubleshooting Petdex or the container runtime before investigating the tunnel.
Operate the local development environment
The full-stack command is a development process. Keep the terminal that started it available so you can see application and container output while testing. A public tunnel does not keep Petdex running, and Petdex does not remain reachable merely because a tunnel configuration exists.
Starting a later session
After the initial clone and dependency installation, return to the repository directory and run the documented full-stack command again:
cd petdex
bun run dev:docker
Re-run bun install when the checked-out dependency definition has changed or when project instructions specifically require it. Avoid running installation commands repeatedly as a substitute for reading a concrete startup error.
Stopping the session
Terminate the foreground development process when you finish. Container cleanup and persistence behavior can vary with the repository revision and selected runtime. The supplied project evidence does not establish a canonical Petdex-specific teardown command, so this guide does not invent one. If containers remain after the foreground process ends, inspect them with your chosen runtime and follow the current repository's documented cleanup procedure.
Stop the Localtonet tunnel separately. A tunnel and its target application have independent lifecycles. Stopping Petdex while leaving the tunnel active can result in a public address that remains assigned but cannot reach its local target. Stopping the tunnel does not shut down Petdex.
Updating the repository
Petdex is actively maintained, so commands, dependencies, migrations, and container definitions can change. Before updating, preserve uncommitted work in an appropriate Git workflow. After obtaining a newer revision, review project changes and refresh dependencies when required by that revision. Do not assume that an environment created by an older commit is compatible with every future commit.
Understand the limits of this deployment path
The repository calls this local development. It does not establish production requirements for scaling, durable database operation, backups, secrets management, observability, edge caching, high availability, or production access control. Localtonet can make the working HTTP endpoint reachable, but a tunnel does not convert a development stack into a production deployment.
Share the working Petdex interface with Localtonet
Once Petdex works at http://localhost:3000, the next step is to expose that HTTP service. With Localtonet, the client application on your device establishes an outbound connection to one of our relay servers. This avoids inbound router port forwarding, firewall changes, VPN setup, and the requirement for a public IP address.
An HTTP tunnel points to a local IP address and port on, or reachable from, the device running our client. For this workflow, the service is Petdex on port 3000. If our client runs on the Petdex machine, use the loopback address represented by localhost or its equivalent local IP entry in the current dashboard. If it runs elsewhere, use an address that the client device can actually reach and test that route before creating the tunnel.
HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. These process types serve the content through a public HTTPS address. Availability can vary, and custom-domain DNS requirements should always be checked against the current dashboard and documentation rather than inferred from an older tutorial.
Install and run the Localtonet client
Run our client on the Petdex machine or on another device that can reach the Petdex service. The client must remain connected for the tunnel to be available.
Authenticate and select the client device
Use the device-specific authentication token associated with the client that will run the tunnel. Select the correct device in the dashboard and never place its token in source code, screenshots, logs, or this article's example commands.
Select an available relay server
Choose a server or region currently offered in your Localtonet dashboard. Available server codes and regions can vary, so do not copy a hardcoded value from an unrelated setup.
Create an HTTP tunnel to Petdex
Configure the tunnel as HTTP and point its local target to the IP address that reaches Petdex and port 3000. Choose an available process type appropriate for the preview. A generated subdomain is generally sufficient for a temporary development share.
Start the tunnel
Creating the tunnel does not start it. Use the Start button and confirm that both the selected client device and tunnel show the expected connected state.
Test the assigned public HTTPS address
Open the assigned URL in a separate browser session and verify the same routes you tested locally. When the preview is finished, stop or delete the tunnel according to whether you expect to reuse its configuration.
For the current dashboard workflow and field definitions, consult our Localtonet HTTP tunnel documentation. Current documentation should take precedence if the dashboard changes after this draft is reviewed.
| Layer | Expected address or state | What a failure usually means |
|---|---|---|
| Petdex application | http://localhost:3000 works on the development machine. |
The application, dependencies, port, or supporting development services need attention. |
| Client-to-target path | The Localtonet client device can reach the configured local IP and port 3000. | The target address, local routing, service binding, or host firewall is preventing access. |
| Localtonet device | The selected device is connected through its own device-specific token. | The wrong device may be selected, or the client may not be running and connected. |
| HTTP tunnel | The tunnel has been created and explicitly started. | A saved configuration may exist without a running tunnel. |
| Remote browser | The assigned public HTTPS URL loads the intended Petdex interface. | Check tunnel state, target accuracy, application host behavior, and browser-visible errors. |
Security guidance for sharing a development instance
A Localtonet HTTP tunnel gives the Petdex service a public address. Anyone who can reach that address may be able to request routes exposed by the development application unless the application itself enforces authentication or another access control. Do not assume that an unguessable-looking URL is authorization.
Before sharing, determine what the running development stack exposes. Petdex contains more than a gallery landing page. Its repository includes API routes, submission-related behavior, CLI endpoints, database-backed surfaces, and administrative functionality. The exact behavior of the containerized development environment can evolve, so review the current application rather than assuming every route is harmless.
Localtonet provides connectivity to the configured local service. It does not replace application authentication, authorization, input validation, safe development data, secrets management, or production deployment controls. Expose only a reviewed instance, use least privilege, and stop the tunnel as soon as the remote preview is complete.
Use non-sensitive development data
Do not populate the preview with real user information, private assets, production database copies, or confidential credentials. Development interfaces often reveal more diagnostic detail than production systems, and errors may include route names, stack traces, identifiers, or configuration clues.
Keep authentication material private
The Localtonet device token identifies the client device and must not be disclosed. Petdex-related Clerk credentials, database credentials, storage credentials, and other environment values must also remain private. Do not paste tokens into public commands, commit environment files, or expose logs during screen sharing.
Share the narrowest useful surface
Use an HTTP tunnel for the Petdex browser application rather than exposing unrelated raw ports. Do not publish PostgreSQL, Redis, container management sockets, debugging listeners, or desktop hook servers simply because they exist on the machine. The remote reviewer normally needs only the web interface on port 3000.
Limit the exposure window
Start the tunnel shortly before the review and stop it when the session ends. Remember that deleting a browser tab does not stop a tunnel. Likewise, stopping the Petdex process does not automatically remove or delete the Localtonet configuration.
Test from an external perspective
Open the assigned URL in a private browser window or on another device. This helps reveal whether the preview depends on an existing local session, whether expected assets load through the public hostname, and whether a route exposes more than intended. Do not ask a reviewer to perform the first external test.
Troubleshoot Petdex and tunnel problems
bun install fails
Confirm that Bun is installed and that the terminal can reach the package sources required by the repository. Read the first meaningful error rather than only the final failure summary. Network restrictions, an unsupported local tool version, insufficient disk space, or a changed project dependency can all stop installation.
Do not work around an installation error by switching package managers unless the current Petdex repository explicitly supports that alternative for its full-stack workflow. The documented sequence uses Bun, and the repository includes a Bun lockfile.
bun run dev:docker cannot start
Check whether Docker or Podman is running and accessible to the current account. Runtime connection and permission errors should be solved at the container layer. If the message identifies an occupied port, determine which local process is using port 3000 and decide whether to stop that process. This guide does not prescribe platform-specific process commands because they differ across operating systems.
On a first run, allow time for required resources to download and initialize. If progress has genuinely stopped, retain the full terminal output. Avoid repeatedly deleting caches or containers without understanding which startup stage failed.
The browser cannot open localhost:3000
Make sure the development process is still running. Review its output for compilation failures, dependency errors, service readiness problems, or port conflicts. Confirm that you are using HTTP and port 3000 exactly as documented. A Localtonet tunnel should remain disabled until this local URL works.
The root page loads but a feature fails
Identify whether the failure concerns a browser asset, Next.js route, API endpoint, database operation, authentication flow, or external-service integration. The containerized workflow is the documented local full stack, but that does not guarantee that every production-integrated behavior can be exercised identically without current project-specific configuration.
If a feature clearly expects real service credentials, do not invent them. The repository reserves the .env.local real-services workflow for maintainers, so obtain approved configuration from the project maintainers when that path is genuinely required.
The Localtonet client cannot reach Petdex
If both run on the same machine, recheck the tunnel's local IP and port. If they run on separate devices, open the Petdex address from the Localtonet client device using ordinary private-network connectivity. Failure at that stage indicates a local binding, routing, or firewall issue rather than a relay problem.
Some development servers listen only on a loopback interface. The supplied Petdex evidence confirms localhost:3000 but does not establish a documented command-line flag for binding Petdex to every network interface. Do not invent a host flag. The simplest evidence-backed arrangement is to run our client on the same machine as Petdex.
The public URL does not work
Check the layers in order. First confirm Petdex locally. Next confirm that the selected Localtonet device is connected. Then confirm that the HTTP tunnel targets the correct address and port. Finally, verify that the tunnel was started, since creating a tunnel does not make it run automatically.
The public page loads incorrectly
Compare the browser's behavior at the public HTTPS URL with the local HTTP URL. Look for failed assets, redirects, authentication callbacks, hostname assumptions, or application errors. The available evidence does not document every Petdex behavior behind an alternate public hostname, so diagnose the actual browser and terminal output rather than applying speculative configuration.
The URL stopped working after previously succeeding
Confirm that the Petdex development process is still active, the Localtonet client remains connected, and the tunnel is still running. Tunnels are available only while the selected client or device is connected and the tunnel is running. A machine sleeping, a terminated development process, or a stopped tunnel can interrupt access.
Frequently asked questions
What command starts the Petdex local full stack?
From the cloned repository, install dependencies with bun install and start the supported Docker or Podman environment with bun run dev:docker. Petdex then instructs developers to open http://localhost:3000.
Can I use Podman instead of Docker?
Yes. The Petdex repository describes Docker or Podman as supported for the local full-stack workflow, even though the script itself is named dev:docker.
Should I use bun run dev instead?
Not for the normal self-contained local workflow. Petdex documents bun run dev as running against real services with a populated .env.local, and labels that path for maintainers. Use bun run dev:docker unless you have the approved real-service configuration.
Is this a production deployment of Petdex?
No. The documented repository workflow is local development. It does not establish production procedures for high availability, scaling, durable storage, backups, secrets, monitoring, or production security controls. Adding a tunnel does not change that status.
Which Petdex port should the Localtonet HTTP tunnel target?
Target port 3000, which is the documented local web endpoint for this development workflow. The local IP must be reachable from the device running our client. Running Petdex and Localtonet on the same machine is the simplest arrangement.
Does creating the HTTP tunnel immediately make Petdex public?
No. Creating a Localtonet tunnel does not mean it is running. You must start it, and the selected client device must remain connected. You can later stop or delete the tunnel.
Does the public HTTPS address secure every Petdex route?
It provides the public HTTPS address for the HTTP tunnel, but it does not replace Petdex application authentication or authorization. Review the development instance, avoid sensitive data, and expose it only for the required period.
Do I need router port forwarding or a public IP address?
No. 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.
Can the Localtonet client run on another computer?
Yes, provided that computer can reach the Petdex service over the local network. However, the supplied Petdex documentation confirms only the loopback URL localhost:3000 and does not establish a supported host-binding flag. Running our client on the Petdex machine avoids that uncertainty.
Is running the repository required just to install a Petdex pet?
No. The repository's full-stack workflow is for developing or evaluating the Petdex web application. End users can install an existing pet through the Petdex CLI and use Petdex Desktop without running the entire website stack locally.
Share your verified Petdex development preview with Localtonet
Start Petdex locally, confirm that http://localhost:3000 works, then connect that HTTP endpoint to a temporary public HTTPS address through our platform. Keep the preview limited to reviewed development data and stop the tunnel when collaboration is complete.
