# Self-host Workmates

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](https://github.com/Sidiora-Labs/workmates-ai) 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

1. Open [Deploy Workmates on Railway](https://railway.com/deploy/workmates) and select your Railway workspace.
2. Review the Workmates service and its persistent volume mounted at `/data`, then deploy. Choose storage capacity appropriate for your files and usage.
3. After the service starts, open its **Variables** tab and copy `WORKMATES_SERVER_TOKEN`. This is your server access key.
4. Open the generated HTTPS domain and sign in with that key.
5. 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.

1. Create a Railway service from the [Workmates repository](https://github.com/Sidiora-Labs/workmates-ai), using its root `Dockerfile`, or select a published `paxeer/workmates-ai` image from [Docker Hub](https://hub.docker.com/r/paxeer/workmates-ai).
2. Attach a persistent volume at `/data` and keep the service at one replica.
3. Generate an access key locally with `openssl rand -hex 32`. Save it as `WORKMATES_SERVER_TOKEN` in the service’s **Variables** tab.
4. Set the startup health check to `/api/health`. Repository deployments already declare this in `railway.json`.
5. 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`.
6. 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](https://docs.railway.com/volumes), [public networking](https://docs.railway.com/networking/public-networking), and [startup health checks](https://docs.railway.com/deployments/healthchecks) 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:

```sh
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:

```sh
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

1. Download an installer for your platform from the [Workmates releases](https://github.com/Sidiora-Labs/workmates-ai/releases).
2. Open the app and choose **Cloud server**.
3. Enter the HTTPS **Server address** and **Server access key**.
4. 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**:

1. Obtain a key from the [Box API key guide](https://docs.ascii.dev/box/api-keys) and ensure that the account can create computers.
2. In **Settings → Apps**, save the **Box API key**. You can also enter it in an agent’s Computer panel when prompted.
3. Open the agent’s Computer settings and select **Cloud box**.
4. 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](/docs/capabilities/computer) 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](https://github.com/Sidiora-Labs/workmates-ai/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:

```sh
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](https://github.com/Sidiora-Labs/workmates-ai/blob/main/docs/CLOUD_SERVER.md). For everyday use, continue with [your first conversation](/docs/getting-started/first-conversation).