Run your own Workmates server on Railway or Docker, then use the same workspace from a browser, phone, or installed desktop app.

Choose where your workspace runs

The workmates-ai project includes an agent server, web/PWA interface, and Electron desktop app. A cloud server runs your agents and stores their conversations, credentials, skills, and files. Your devices connect to that shared workspace.

Setup	Where work runs	How you open it
Cloud server	Your Railway service or container host	Hosted website, mobile PWA, or desktop app in Cloud server mode
Local server	Your own computer	Desktop app in This computer mode, or the local development website

Choose cloud hosting when you want to return to the same workspace from several devices. Choose local mode when agents need your laptop’s folders, native desktop control, or Local VM. Switching the desktop app between modes keeps the local and cloud workspaces separate.

You will need a hosting account or container host, persistent storage, and your own model-provider connection. Hosting, model usage, and optional computer services are billed by their respective providers.

Deploy with the Railway template

Open Deploy Workmates on Railway and select your Railway workspace.
Review the Workmates service and its persistent volume mounted at /data, then deploy. Choose storage capacity appropriate for your files and usage.
After the service starts, open its Variables tab and copy WORKMATES_SERVER_TOKEN. This is your server access key.
Open the generated HTTPS domain and sign in with that key.
Continue to Connect a model provider below, then send a first message.

The template uses a prebuilt server-and-web image, a generated access key, and the /api/health startup check. Keep one service replica: this installation stores a single workspace in files on its volume.

Set up Railway manually

Use this route if you want to deploy your own checkout or choose the image yourself.

Create a Railway service from the Workmates repository, using its root Dockerfile, or select a published paxeer/workmates-ai image from Docker Hub.
Attach a persistent volume at /data and keep the service at one replica.
Generate an access key locally with openssl rand -hex 32. Save it as WORKMATES_SERVER_TOKEN in the service’s Variables tab.
Set the startup health check to /api/health. Repository deployments already declare this in railway.json.
In Settings → Networking → Public Networking, generate a domain. The container defaults to port 8080; its domain target and health-check port must match the server’s configured PORT.
Deploy, open the HTTPS address, and sign in.

For a Railway-provided domain, Workmates reads RAILWAY_PUBLIC_DOMAIN. For your own domain, finish its Railway DNS setup and set WORKMATES_PUBLIC_URL to the exact HTTPS origin, such as https://workmates.example.com. Use that address on every device.

Railway explains persistent volumes, public networking, and startup health checks in its platform guides.

Run the container yourself

The published cloud image targets Linux amd64 and includes the server, web interface, Node.js, Python, Git, curl, and SSH tools. Use a compatible Docker host. The following example starts a fresh workspace on the host’s loopback address.

Create a private environment file first. These commands use a POSIX shell and OpenSSL:

mkdir -p workmates-host
cd workmates-host
umask 077
printf 'WORKMATES_SERVER_TOKEN=%s\n' "$(openssl rand -hex 32)" > workmates.env
printf '%s\n' 'WORKMATES_PUBLIC_URL=http://127.0.0.1:8080' >> workmates.env

Then create the data volume and start Workmates:

docker volume create workmates-data
docker run --detach \
  --name workmates \
  --restart unless-stopped \
  --env-file workmates.env \
  --publish 127.0.0.1:8080:8080 \
  --volume workmates-data:/data \
  paxeer/workmates-ai:latest

Open http://127.0.0.1:8080 on that host. Read the access key from your private workmates.env file and use it to sign in. Once you choose a release, replace latest with its published version tag or image digest so subsequent starts use the same build.

Publish it over HTTPS

For access from another device, put the container behind an HTTPS reverse proxy and set WORKMATES_PUBLIC_URL to its public origin. Forward requests to container port 8080 and preserve the original host and HTTPS forwarding headers. Allow streaming responses so conversation updates arrive as agents work.

If the proxy runs on the same host, it can use the loopback binding above. If it runs in another container, connect both containers to a shared Docker network and address Workmates by its container name. Redeploy Workmates after changing its environment file.

The public URL is an origin only: a scheme and hostname, with an optional port. Serve Workmates at the domain root, such as https://workmates.example.com, rather than under /workmates. HTTPS enables browser installation and secure sign-in on phones and other computers.

Server settings

The official image supplies the defaults below. Keep /data attached when replacing or upgrading the container.

Variable	Value or purpose
`WORKMATES_SERVER_TOKEN`	Your generated access key; at least 32 characters, without whitespace
`WORKMATES_HOSTED`	`1` to run the authenticated cloud server
`WORKMATES_DATA_DIR`	`/data/workspace`, where the workspace is stored
`WORKMATES_STATIC_DIR`	`/app/dist`, the bundled web/PWA interface
`PORT`	`8080` by default; Railway can supply this value
`WORKMATES_PUBLIC_URL`	Public HTTPS origin; overrides Railway domain detection

The server listens on all container interfaces in hosted mode. If you set WORKMATES_PORT, it takes precedence over PORT; keep the proxy, exposed port, and health check aligned.

Connect a model provider

Open Settings → Engines after signing in. Connect OpenRouter or another supported API provider using its own API key. The server manages these connections, so every client uses the same configured providers.

For Centra Gateway or another OpenAI-compatible service, add a custom endpoint in the Engines settings. Enter a name, the provider’s base URL, and its API key. For Centra Gateway, the base URL is https://gateway.centra.ag/v1.

Create or open an agent and choose the connected provider in its model picker. Use Search models to filter the returned catalog by name or model ID. If a model is missing, check that the endpoint’s model catalog and your provider account expose it.

Send a short first request, then try a task with the tools you intend to use. An engine that depends on a CLI needs that CLI installed and authenticated on the server. For persistent CLI additions, build a derived container image; your laptop’s installed CLIs are used only by a local workspace.

Open the same workspace on your devices

Browser and phone

Open the server’s HTTPS address and sign in with the server access key. On a supported browser, choose Install app or Add to Home Screen for a standalone app window.

The browser and PWA share the server’s agents, conversations, and uploaded files. Chats and tools need an internet connection; reconnect to the same address to resume. The server can continue agent work while your browser is closed.

Use Settings → General → Sign out of this device to end that browser session.

Installed desktop app

Download an installer for your platform from the Workmates releases.
Open the app and choose Cloud server.
Enter the HTTPS Server address and Server access key.
Select Connect workspace.

You can change the connection later in Settings → General. Where available, choose Remember the key in this computer’s secure storage. Otherwise, the key lasts for the current app session.

Attachments selected on your laptop upload to the cloud workspace. For files that should stay directly accessible on your laptop, use This computer mode with a local server. Changing modes does not migrate files between those workspaces.

Add a cloud computer

For an isolated remote desktop, connect Box by Ascii:

Obtain a key from the Box API key guide and ensure that the account can create computers.
In Settings → Apps, save the Box API key. You can also enter it in an agent’s Computer panel when prompted.
Open the agent’s Computer settings and select Cloud box.
Allow provisioning to finish, then choose Open desktop.

A hosted workspace uses Cloud box for interactive desktop work. This computer and Local VM are available when Workmates runs with a local server. Installing the desktop client alone does not give a cloud agent control of that client’s computer.

If provisioning reports a provider error, check the Box key, account quota, and billing status. If the desktop is blocked or fails to load, confirm that you are using the configured Workmates HTTPS origin, refresh the app, and inspect the server’s computer-proxy error. Continue with computer workflows once the desktop opens.

Keep your workspace through updates

Store project working folders under /data when they must survive container replacement. Back up the full volume, including /data/workspace, and any project folders stored elsewhere. Pause agent activity and stop the server for a consistent filesystem copy, or use the hosting platform’s volume-backup facility.

Cloud releases publish image tags and exact digests in GitHub releases. Choose a release, preserve the existing /data volume and access key, and redeploy the service with the new image. Expect a brief interruption while a service with an attached volume restarts.

After an update, sign in and check an existing conversation, an uploaded file, your provider connection, and a new agent reply. Browser and desktop clients should show the same workspace.

To change the server access key, update WORKMATES_SERVER_TOKEN and restart the server. Sign in again in your browsers and update the saved key in desktop clients.

Check a new installation

First check the server endpoint:

curl --fail --silent --show-error https://workmates.example.com/api/health

Replace the example domain with yours. The response identifies app as workmates and mode as hosted. An unauthenticated request reports authenticated: false; sign in through the app to access your workspace.

Then create an agent, send a message through your provider, upload a small file, and open the same conversation from a second device. If you connected Box, open its desktop as well.

Symptom	What to check
Server stops at startup	The access key has at least 32 characters; the public URL is a valid origin; the volume is writable
Railway health check fails	`PORT`, the domain target port, `/api/health`, and the server’s startup logs
Sign-in fails	The access key matches the current service variable and you opened the configured public URL
Sign-in cannot be saved	The `/data` volume is attached and writable
Desktop opens different conversations	The app is connected to Cloud server with the intended URL
Provider is connected but no reply arrives	The agent’s selected engine, provider error, account access, and available model catalog
Computer options are unavailable	Use Cloud box for a hosted workspace, or connect the desktop app to a local server
Files disappear after redeploying	The original volume is still attached and the working folder is under `/data`

For build details and the server’s deployment files, see cloud server setup in the project. For everyday use, continue with your first conversation.

Self-host Workmates