Deploy Capy Host

Deploy and Host Capy Host on Railway (remote AI coding agents, self hosted)

Run Capy's AI coding agents on an always-on cloud server instead of your laptop. This template installs the official Capy Dock CLI on a persistent Railway service and pairs it to your Capy workspace, so it shows up under Run on next to your other devices. Your AI coding threads keep running when your laptop is closed, asleep or offline, and the agents work in a clean Linux environment with git, Node.js and Python ready.

Pairing takes one click. After the first deploy, open the deploy logs, click the [pairing] link, and approve it in your browser. The template answers Dock's confirmation prompt for you, then logs Connected in . No terminal, no SSH, no tokens to copy.

About Hosting Capy Host

Capy runs coding threads on a device you choose. Dock is the small CLI that turns a machine into one of those devices: while capy dock runs, the machine is online in Capy, and when it stops, the machine goes offline. A laptop that sleeps or loses Wi-Fi drops off. A server does not.

This template builds a Debian image with everything Dock needs (git, gh, Node.js 22, Python 3, build tools, tmux), installs Dock as an unprivileged capy user (Dock refuses to run as root), and keeps capy dock alive in a tmux session that restarts if it exits. Pairing, worktrees and your linked folders live on a persistent volume, so redeploys and restarts stay paired.

The host connects outward to api.capy.ai. It needs no public domain, no open ports and no inbound networking.

Why Deploy on Railway

Railway gives you a Linux box with a persistent volume, logs in the dashboard, restarts on failure and usage-based billing. An idle host costs little, and you pay for compute while threads work.

Common Use Cases

• Long-running AI coding tasks. Hand an agent a big refactor, migration or backlog of bugs and close your laptop.
• Parallel AI agents. Run several coding threads at once, each in its own git worktree, stored under ~/.capy/worktrees on the volume.
• A clean, dedicated environment. Capy's docs recommend a dedicated account on shared servers, because threads get that user's permissions. A single-purpose Railway project is exactly that.
• Always-available device. Pick it from Run on whenever you start a thread, without keeping a laptop awake.
• Heavier builds and test suites. Give the agents more CPU and RAM than your laptop has.
• A cloud dev box for AI agents. Keep agent-generated code and tooling off your personal machine.

Dependencies for Capy Host Hosting

The template needs one service running the Dock CLI, a persistent volume, and your Capy workspace. Railway provisions the first two, so you only bring a Capy account. No public domain or inbound ports are needed, because the host connects outward to Capy.

Deployment Dependencies

• The service built from the template repo Dockerfile (Debian, git, gh, Node.js 22, Python 3, tmux)
• A Railway volume mounted at /home/capy
• A Capy account and workspace (see capy.ai for plans)
• Capy's Dock CLI, installed automatically at first boot from Capy's official installer
• Optional: a GitHub login on the host for gh and private repos

Implementation Details (environment variables)

All variables are optional and the defaults work for most people.

How to Use Capy Host After Deploying

1. Deploy the template and wait for the build to finish (a few minutes the first time).
2. Open the service's Deploy Logs and find the line starting with [pairing] Open this link to pair this host with Capy.
3. Click the link and approve it in your browser. Only approve a code you generated yourself.
4. Watch the logs. You should see Confirmed (Yes) and then Connected in .
5. In Capy, open Run on and select the new device. Start a thread.

If the code expires before you click, Dock generates a new one (roughly every 10 minutes) and the template logs the new link automatically.

Redeploys

Pairing is stored on the volume, so a redeploy comes back online by itself. No new link is printed. The hostname changes on every deploy (it is the container ID), which is cosmetic. You can rename the device in Capy's device settings.

GitHub and git

Capy may handle repository access itself, so try a thread first. If a thread needs gh or private repos on the host, set TERMINAL_PASSWORD and PORT=8080, generate a domain, open it, press Ctrl-b c for a new shell window and run gh auth login, then gh auth setup-git and git config --global user.name / user.email. All of it is saved on the volume. Remove the domain and password afterwards if you don't want a public terminal.

Useful commands

Run these in a shell on the service (web terminal or railway ssh, then su - capy):

• capy dock status: run state and paired organization
• capy dock doctor: checks install, pairing, dependencies and connectivity

Security Notes

• The pairing link appears in the deploy logs. Anyone who can read this project's logs could approve the code into their own Capy workspace before you do. Pair right after deploying, keep the project private, and for shared projects set PAIRING_IN_LOGS=false and pair from the web terminal instead. Once paired, the old link does nothing.
• Threads run with the capy user's permissions and can see the service's environment variables. Use a dedicated Railway project, and don't put secrets in it that you wouldn't give a coding agent.
• Auto-confirm answers Dock's "Pair this machine with ...?" prompt for you. You still have to approve the code in your own browser first, so nothing pairs without your approval.
• Use one replica. Capy allows one device per user per machine.
• To remove the host, choose Revoke device in Capy's device settings.

Is Capy Host Free? (License and Pricing)

The template is free to deploy. You pay Railway for usage (CPU, RAM, volume and network) and Capy for whatever plan you are on. Idle time costs little because the host mostly waits for threads. Heavy builds and many parallel threads cost more, so size the service to the work. See capy.ai for current Capy pricing.

Troubleshooting

• No [pairing] line in the logs. If the host is already paired, none is printed. Look for Connected .... If you want to re-pair, revoke the device in Capy and restart the service.
• Device shows "never connected" in Capy. Dock was waiting at its confirmation prompt. With PAIRING_AUTO_CONFIRM=true the template answers it. If the logs say Could not confirm automatically, answer it by hand in the web terminal or over SSH (tmux attach -t dock).
• Pairing link expired. Dock rotates the code about every 10 minutes. A new link is logged each time. Click the latest one.
• Host is offline after a redeploy. Check that the volume is mounted at /home/capy. Without it, pairing is lost on every deploy.
• Stale devices listed in Capy. Each abandoned attempt can leave an entry without a token. Revoke them in device settings.
• Threads can't clone private repos. Log in with gh auth login as described above.
• Permission errors. Dock runs as uid 1000 (capy). Files on the volume must be owned by that user. The entrypoint repairs ownership at boot.
• Alpine or musl images. Dock needs glibc Linux (x64 or arm64). Don't replace the base image with Alpine.

FAQs

Do I need a public domain? No. The host connects outward to Capy. The domain is only for the optional web terminal.

Does it stay paired after redeploys? Yes, as long as the volume stays attached.

How do I update Dock? Set CAPY_AUTO_UPDATE=true and redeploy, or run the Dock installer again in a shell.

Is this an official Capy template? No. It is an independent template that installs Capy's published Dock CLI.

Related Templates

• Paradev Host: run Paradev coding agents on an always-on Railway host
• Paseo Daemon: headless remote coding agents with a web UI
• n8n with workers and task runner: n8n in queue mode with Redis and Postgres
• n8n with FFmpeg: n8n with FFmpeg on the workers

[Updated Nov '26]