Self-Host Rakazo and Access It with Localtonet

What you are deploying

Rakazo is an open-source platform for running persistent AI teammates. A bot can maintain its own conversations, memory, routines, and history, while the platform provides browser, terminal, file, and graphical desktop access. Rakazo supports bring-your-own model credentials and can connect to computer providers and integration systems configured by the operator.

The project includes a React and Vite web interface, a backend API, PostgreSQL storage, worker processes, and computer or sandbox integrations. Rakazo also provides Electron desktop and Expo mobile clients. Those clients use the same Rakazo API as the web application, so a remotely reachable server can support browser, desktop, and mobile access without deploying separate backend services for each client.

Rakazo is currently described by its maintainers as beta software. That matters when planning a deployment. Treat it as an actively changing application, review release information before upgrading, maintain backups of important data, and test changes before relying on the server for critical workflows.

How the Localtonet connection fits

Rakazo must be installed, started, and verified before adding remote access. Once the web service responds on the server, the Localtonet client running on that server establishes an outbound connection to one of our relay servers. The HTTP tunnel then provides a public HTTPS address that forwards requests to Rakazo's local HTTP listener.

This arrangement does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The public endpoint remains dependent on both applications: Rakazo must be running locally, and the selected Localtonet client and tunnel must also remain connected.

Prerequisites and deployment choices

The shortest documented installation path uses Rakazo's published container images. For that path, the server needs Docker Engine, the Docker Compose plugin, curl, and OpenSSL. You do not need to clone the source repository, install Node.js, or install pnpm.

The server also needs enough resources for the Rakazo services and whichever local computer or sandbox workloads you enable. The available evidence does not establish a universal CPU, memory, or disk minimum, so we do not recommend inventing a fixed size. Actual requirements depend on bot activity, browser workloads, retained data, enabled providers, and whether execution happens locally or through a remote computer provider.

Choose between published images and a source checkout

Supported Node.js versions for source development

If you choose the source workflow, Rakazo documents Node.js 22.22.2 or newer within the 22.x line, Node.js 24.x, or Node.js 26 and newer. Node.js 23.x and 25.x are not supported. The source workflow also requires pnpm 9 and Docker.

These Node.js requirements apply to the source checkout. They do not apply to the published-image quick start because that installation does not require a local Node.js installation.

Network planning

The web endpoint is the component intended for browser access. Do not expose PostgreSQL as a substitute for the web endpoint. In the default Compose arrangement, PostgreSQL remains network-internal. The development overlay can publish PostgreSQL only on loopback at 127.0.0.1:5433 so host-side pnpm commands and database tools can reach it.

Localtonet should run on the Rakazo server or another device that can reach the Rakazo HTTP service. The simplest arrangement is to run our client on the same host and configure the HTTP tunnel for 127.0.0.1 on port 5173. If the client runs elsewhere, the local target must be an address reachable from that client device. Do not assume that another machine's 127.0.0.1 points to the Rakazo server, because loopback always refers to the machine making the connection.

Install Rakazo with published Docker images

The published-image installer is the most direct route to a working self-hosted instance. It creates a local Rakazo directory, downloads the official bootstrap script, obtains the Compose files, creates a .env file with random secrets, and starts the stack.

The complete quick-start command is:

mkdir -p rakazo && cd rakazo && curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh && bash install-images.sh

Let the script finish before attempting to open the application. The default image tag is edge, built from the main branch for linux/amd64 and linux/arm64. Because an edge tag can change as the project evolves, review project release and self-hosting guidance before treating an update as production-ready.

Preparing a server before starting it

For a server where you want to select a remote computer provider or set the externally used host value before startup, Rakazo documents a prepare-only mode:

bash install-images.sh --prepare-only

After preparation, edit .env. Rakazo's documented server example sets SANDBOX_PROVIDER to box, e2b, or daytona, adds the matching provider API key, and sets RAKAZO_HOST to the chosen host. Then run the installer normally:

bash install-images.sh

Provider selection is deployment-specific. Do not copy a provider name unless you actually have that provider account and its corresponding API key. Do not place API keys in shell history, screenshots, support messages, or a public repository.

Restricted download networks

Rakazo documents several mechanisms for networks that cannot retrieve the normal installer assets directly. The installer download base can be overridden with RAKAZO_DOWNLOAD_BASE. Existing Compose files can be retained by using --local or RAKAZO_DOWNLOAD_SKIP_EXISTING. The bootstrap script URL can also be mirrored.

A mirror becomes part of your software supply chain. Only use a mirror you control or trust, confirm what it serves, and keep the mirrored files synchronized intentionally. A successful download is not, by itself, proof that a mirrored script is authentic.

Configure credentials, providers, and host behavior

The published-image installer generates random secrets in .env. Protect this file as a credential store. It can contain database credentials, authentication secrets, encryption-related values, provider keys, and tokens that should never be committed to version control or exposed through a web server.

In a source installation, Rakazo requires deliberate secret configuration. POSTGRES_PASSWORD must match the password embedded in DATABASE_URL. The project recommends a URI-safe PostgreSQL password and gives openssl rand -hex 16 as an example. It also requires BETTER_AUTH_SECRET, ENCRYPTION_KEY, and SCREEN_PROXY_SECRET to be independent long random values. Docker sandboxes additionally need a dedicated SANDBOX_SUPERVISOR_TOKEN.

“Independent” is important. Do not reuse the database password as an authentication secret, encryption key, screen proxy secret, sandbox token, Localtonet device token, or provider API key. If one credential is disclosed, reuse would unnecessarily compromise other parts of the deployment.

Model configuration

You may set OPENROUTER_API_KEY before startup, or connect a supported model provider during Rakazo's onboarding. This means the application can start without placing every optional integration credential into the initial environment file, but a usable bot still needs access to a supported model configuration.

Optional integration catalogs

Managed application catalogs are optional. Rakazo documents COMPOSIO_API_KEY for Composio. Pipedream Connect requires the PIPEDREAM_CLIENT_ID, PIPEDREAM_CLIENT_SECRET, and PIPEDREAM_PROJECT_ID values together.

Users may also add an HTTPS MCP server, a Treg endpoint, or an OpenAPI JSON document from Rakazo's Integrations area without enabling either managed catalog. Rakazo states that connector credentials are encrypted on the server and are not returned by its API. Treg is usage-metered, and self-hosters must supply their own Treg token.

Alternative: install Rakazo from source

Use the source workflow when you need to develop Rakazo, inspect or modify the code, or run the monorepo's development processes. For an ordinary server installation, published images involve fewer moving parts.

Run the following checkout and environment preparation commands:

git clone https://github.com/elie222/rakazo.git
cd rakazo
cp .env.example .env

Generate the documented example of a URI-safe PostgreSQL password:

openssl rand -hex 16

Store the generated value as POSTGRES_PASSWORD, and use the same value in DATABASE_URL. Because the exact surrounding database URL depends on the provided environment template, edit the copied template rather than inventing a connection string from scratch.

After all required secrets have been configured, start PostgreSQL:

docker compose --env-file .env \
  -f infra/compose/docker-compose.yml \
  -f infra/compose/docker-compose.postgres-host.yml \
  up postgres -d

Then install dependencies, generate the database client, apply migrations, build the sandbox, and start the development environment:

pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build
pnpm dev

Accessing PostgreSQL without the host overlay

If you intentionally do not use the host overlay, PostgreSQL remains inside the Compose network. Rakazo documents opening a PostgreSQL shell through the running container:

docker compose --env-file .env -f infra/compose/docker-compose.yml exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

Persistent volume behavior

An existing pgdata volume retains the database user, password, and database created during its first initialization. Keep the matching values in .env, or change the database values in place using the appropriate PostgreSQL administration procedure.

Verify Rakazo locally before exposing it

Local verification separates application problems from tunnel problems. On the Rakazo host, open:

http://127.0.0.1:5173

A successful installation should present the Rakazo web interface. Create an account, complete onboarding, connect a model provider if one was not configured in advance, and create a first bot. The published-image installation enables local Docker computers by default.

Do not proceed merely because containers exist. Confirm that the browser receives the application, account creation works, and the expected onboarding flow loads. If the page fails locally, a public tunnel will forward that same failure.

A practical verification checklist

• The Docker services or development processes remain running without immediately exiting.
• http://127.0.0.1:5173 loads from the Rakazo host.
• The account creation or sign-in interface appears.
• You can complete the relevant onboarding steps.
• A supported model provider can be connected using credentials you control.
• The deployment retains its configuration after an intentional restart.
• PostgreSQL is not publicly reachable as part of the remote-access plan.

Understanding loopback access

The address 127.0.0.1 is the server's IPv4 loopback interface. Binding a service there makes it reachable from processes on that server without automatically listening on every network interface. This is useful with Localtonet because our client can connect to the local service and create an outbound tunnel, while Rakazo itself does not need a publicly listening socket.

If your Localtonet client runs inside a separate container, virtual machine, or another physical host, its loopback interface is not the Rakazo host's loopback interface. In that topology, determine an address through which the client can actually reach Rakazo, and restrict that path appropriately. The supplied evidence does not define a universal container-network address, so use the networking model of your specific deployment rather than assuming a hostname or gateway.

Connect Rakazo through a Localtonet HTTP tunnel

After local verification, use an HTTP tunnel for the Rakazo web interface. No UDP service is established by the documented Rakazo installation, and the database is not the correct public target. The HTTP tunnel should point to the local Rakazo service at IP address 127.0.0.1 and port 5173 when our client runs on the same server.

Current relay choices, account capabilities, process-type availability, and plan limits must be checked in the dashboard. We do not hardcode them because they can change by plan, region, client version, or deployment. For current product guidance, use our Localtonet documentation.

Random subdomain, custom subdomain, or custom domain

If you use a custom domain, check the current Localtonet documentation for its exact DNS requirements. Do not guess DNS record types or values. Rakazo's own RAKAZO_HOST setting may also need to reflect the host through which users access the server, particularly when preparing a server deployment.

Connecting desktop and mobile clients

Rakazo's desktop and mobile applications are clients of the same API used by the web interface. For a server deployment, Rakazo documents choosing Existing instance in the desktop application and entering the server's https:// address. The Localtonet HTTPS URL can serve as that remotely reachable address when the tunnel and Rakazo server are both running.

Do not enter http://127.0.0.1:5173 on a remote laptop or phone. On those devices, that address refers to the laptop or phone itself. Use the assigned public HTTPS address instead.

Operate the deployment safely

Understand the two-part lifecycle

Rakazo and Localtonet have separate lifecycles. Rakazo's backend and containers must remain running for bots and clients to use the server. The Localtonet client must remain connected, and the selected tunnel must be started, for the public address to work.

This gives you a useful operational boundary. You can stop public access without deleting Rakazo data by stopping the tunnel. You can also keep the tunnel configuration for later use, although it will not serve a working application while Rakazo is stopped.

Protect environment files and tokens

• Restrict access to the Rakazo .env file.
• Do not commit .env to source control.
• Keep model, computer-provider, Composio, Pipedream, Treg, and other integration credentials private.
• Keep the Localtonet device token private and device-specific.
• Use independent application secrets rather than reusing a single value.
• Rotate credentials if they appear in logs, terminal recordings, screenshots, or repository history.

Back up persistent data before destructive operations

PostgreSQL persistence is central to the deployment. Before replacing volumes, changing database identity values, or making a major upgrade, take an appropriate database backup and confirm that it can be restored. The available evidence identifies the destructive effect of docker compose down -v, but it does not provide one universal backup command for every installation, storage driver, and Compose layout. Use a backup method appropriate to your actual PostgreSQL deployment.

Approach upgrades conservatively

The published-image quick start defaults to the edge tag. It is built from the project's main branch, so a newly downloaded image can contain changes not present in your current deployment. Read the project's current release and self-hosting notes, back up important state, preserve .env, and schedule an upgrade window that allows validation and rollback planning.

Rerunning the installer preserves an existing .env, but preserving configuration is not the same as backing up application data. Treat environment-file backup and database backup as separate tasks.

Limit public exposure

Start the tunnel only for the period in which remote access is required when continuous access is unnecessary. Remove or disable unused application integrations, grant external providers the minimum permissions needed for their tasks, and regularly review which users can sign in.

Localtonet provides connectivity to the selected target. Application-level identities, bot permissions, model-provider permissions, and integration authorization continue to be controlled by Rakazo and the connected services.

Troubleshooting Rakazo and the tunnel

The local page does not open

First confirm that you are testing from the Rakazo host and using the exact documented endpoint, http://127.0.0.1:5173. Check whether the installer completed and whether the relevant containers remain running. For a source checkout, confirm that pnpm dev is still active and did not exit after reporting an environment, migration, or dependency error.

If PostgreSQL was initialized with different values previously, remember that the existing pgdata volume keeps the original database user, password, and database. Changing only .env does not retroactively change those stored database values. Restore the matching environment values or deliberately update the database in place.

The public URL does not open, but localhost works

Confirm that the Localtonet client on the Rakazo host is connected. Then confirm that the HTTP tunnel was actually started, since creating it is not enough. Verify that its local target is 127.0.0.1 and port 5173, not the database port and not an unrelated container port.

If our client runs somewhere other than the Rakazo host, 127.0.0.1 is probably the wrong target because it points back to the client device. Move the client to the Rakazo host or configure an address the client can legitimately reach.

The public page loads but authentication or redirects fail

Confirm that you are opening the HTTPS URL assigned to the tunnel. For a prepared server deployment, review the configured RAKAZO_HOST and ensure it corresponds to the host users actually enter. If you changed the public hostname after initial configuration, review the current Rakazo server guidance before editing authentication-related settings.

Avoid speculative changes to authentication secrets. Replacing BETTER_AUTH_SECRET, encryption values, or other persisted secrets can have consequences for existing sessions or encrypted data. Back up the deployment and follow current project guidance before rotating them.

A model or integration does not work

Loading the interface proves that the web service is reachable, but it does not prove that every external provider is configured. Check that the expected provider key is present, valid, and authorized for the requested service. Pipedream Connect requires all three documented values, while other providers use their corresponding keys.

Keep provider troubleshooting separate from tunnel troubleshooting. If Rakazo loads through the public URL and an authenticated user can navigate the interface, the tunnel is forwarding HTTP traffic. A later provider error is normally within Rakazo's configuration or the external provider relationship rather than the HTTP tunnel itself.

Source installation fails during dependency setup

Check the Node.js major version first. Node.js 23.x and 25.x are explicitly unsupported. Use Node.js 22.22.2 or newer in the 22.x line, Node.js 24.x, or Node.js 26 and newer, together with pnpm 9. Then rerun the documented sequence without skipping database generation, migrations, or the sandbox build.

The database cannot be reached from host-side tools

The default Compose file keeps PostgreSQL network-internal. For the source workflow, include infra/compose/docker-compose.postgres-host.yml if host-side tools need loopback access at 127.0.0.1:5433. Otherwise, use the documented docker compose exec command to open psql inside the PostgreSQL container.

Frequently asked questions