Isomux docs Set up Isomux on Render
GitHub

Set up Isomux on Render#

Deployment validation is incomplete. Render charges for the compute plan and persistent disk.

This is the Render guide. To check if this is the right hosting setup for you, check the decision diagram.

Render runs the office as one Docker web service on a paid compute plan with a persistent disk. The render.yaml at the root of the isomux repository declares that service, and Render reads it when you create a Blueprint.

You need a Render account, a payment method for the compute plan and disk, an AI provider account, and a domain you control. Apps that agents build get their own subdomains under the office address, and Render's onrender.com addresses cannot provide those. Pick the office address before you start, for example office.example.com. Use a workspace with no other isomux service in it: a Blueprint that names a service already in the workspace takes that service over instead of creating a new one.

  1. Create the service. In the Render dashboard, open New > Blueprint, paste https://github.com/nmamano/isomux into the Public Git Repository field, and keep the main branch on the next screen. Name the Blueprint after the office, for example isomux-office. Render lists one web service with a 20 GB disk and asks for one value, ISOMUX_PUBLIC_URL: enter https:// followed by your office address. Apply, and wait until the new web service shows Live. Render's Blueprint docs.
  2. Point your domain at it. From the Dashboard, open the web service the Blueprint created (named isomux), then Settings > Custom Domains, and add both office.example.com and *.office.example.com (the wildcard serves the apps from the personal software suite on subdomains to avoid using ports). Render shows the DNS records to create at your registrar; copy them exactly (note that the wildcard domain will require 3 CNAME entries; Render will walk you through adding them). Wait until office.example.com shows Certificate Issued; the wildcard's certificate takes longer and is only needed once you open an app. Render's custom domain docs.
  3. Claim the office. Open the service's Environment tab and copy the value of ISOMUX_SETUP_KEY, which Render generated for you. Open your office address in a browser and enter the key and your name. You are the first owner; the key stops working after that, and you add other people through Settings → Invites in the office.

Only the disk, mounted at /var/data, survives a deploy; the rest of the container is rebuilt from the image. Agents' home directory is on the disk, so their default working directory is safe. A project created anywhere else is gone after the next deploy.

Connect a provider and send a message#

In the office, open Settings → You → Individual connections.

  • For Claude or Codex, select the provider's sign-in control and complete the instructions shown. If Isomux asks to install the Claude CLI, complete that step first. Codex is bundled with Isomux.
  • For OpenCode, open or create an OpenCode agent and choose a model. Its model picker offers Free, Pay-as-you-go, and Subscription options. A Free model provides a starting path without a paid provider connection.
  • For a provider API key, add its environment variable in Individual connections: ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENCODE_API_KEY, as applicable.

Open an agent that uses the connected provider and send a short message. A reply confirms that the office can use your provider account. Provider charges and subscription limits are separate from hosting.

For Claude through Amazon Bedrock or another connection method, use the provider reference.

Add people and devices#

For another device of your own, open Settings → You → Sign-in links and create a device link. Open it on that device.

To invite another person, open Settings → Office → Invites, enter their name, select a role and room access, and issue an invite. Send the link privately. Only invite people you trust: members and their agents can run commands on the server with the office's operating-system permissions.

On iPhone, open the office in Safari and select Share → Add to Home Screen. On Android, open the HTTPS office address in Chrome and use its install option.

Apps and later deployments#

To check that app subdomains work, ask an agent to build a small app and open it. Render provides HTTPS for the office and configured app domains.

Automatic deployments are disabled in the Blueprint. To update, use the web service's manual deployment control after you have finished active agent work. A deployment replaces the container and interrupts the office and its apps. Check the office and app URLs after the new deployment is live.

Use Render's service logs for build and container startup failures. Office and app logs are on the persistent disk under /var/data/home/.isomux/container-runtime. Keep projects under /var/data so that replacement does not remove them.

Backups#

Isomux stores seven daily backups of ~/.isomux/ in the server's backup directory on the same disk as the office, so copy them elsewhere if you need protection from server loss. Current backup health and the exact directory are at GET /api/backup/status.

Keep an independent copy or snapshot of the complete persistent disk for recovery from disk loss. The office backup alone does not include all projects and provider files. See the container reference for advanced runtime details.