Skip to content
Back to search

deploy-rakazo

SkillWorks with Claude CodeGitHub

"Use when deploying Rakazo (persistent AI teammates platform) on Railway — one-click template deployment, environment variable configuration, and post-deploy verification."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/phycomp--deploy-zakaro/badge.svg)](/listings/phycomp--deploy-zakaro)

HTML

<a href="/listings/phycomp--deploy-zakaro"><img src="/api/listings/phycomp--deploy-zakaro/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 183 lines
  1. ---
  2. name: deploy-rakazo
  3. description: "Use when deploying Rakazo (persistent AI teammates platform) on Railway — one-click template deployment, environment variable configuration, and post-deploy verification."
  4. ---
  5. # Deploy Rakazo on Railway
  6. ## Overview
  7. Rakazo is an open-source platform for persistent AI teammates with memory, routines, and their own computers (browser, terminal, files, graphical desktop). This skill documents the end-to-end deployment on Railway using the official template.
  8. **Core principle:** Deploy the full stack (web, api, worker, postgres) via Railway's one-click template, configure the optional model/sandbox keys, and verify the first user registration.
  9. ## Prerequisites
  10. - A Railway account (sign up at https://railway.com)
  11. - (Optional) OpenRouter API Key (https://openrouter.ai) for out-of-the-box model access
  12. - (Optional) Sandbox provider API Key (E2B, Daytona, or Box) for bot computer capabilities
  13. ## Deployment Steps
  14. ### 1. Open the Railway Template
  15. Navigate to the Rakazo template page:
  16. ```
  17. https://railway.com/deploy/rakazo
  18. ```
  19. Or directly to the deploy wizard:
  20. ```
  21. https://railway.com/new/template/rakazo
  22. ```
  23. ### 2. Sign In to Railway
  24. Railway supports three login methods:
  25. - **Continue with GitHub** (recommended — also grants repo access for template sources)
  26. - **Continue with Google**
  27. - **Log in using email**
  28. Click "Login" on the deploy page, then choose your preferred method.
  29. ### 3. Review the Template
  30. The template deploys four services:
  31. | Service | Image | Role |
  32. |---------|-------|------|
  33. | `web` | `ghcr.io/elie222/rakazo/app:v0.3.3` | Public web app (Vite preview, port 5173) |
  34. | `api` | `monotykamary/railway-template-rakazo` | Hono API server (port from PORT env) |
  35. | `worker` | `monotykamary/railway-template-rakazo` | Graphile Worker (routines, wakeups) |
  36. | `postgres` | `railwayapp-templates/postgres-ssl:18` | PostgreSQL 18 datastore |
  37. ### 4. Configure Environment Variables
  38. #### Required (auto-generated — do not edit)
  39. - `BETTER_AUTH_SECRET` — signing secret for auth sessions
  40. - `ENCRYPTION_KEY` — AES key for stored credentials (never regenerate after first deploy)
  41. - `SCREEN_PROXY_SECRET` — shared signing secret for browser-screen capabilities
  42. - `POSTGRES_PASSWORD` — auto-generated Postgres password
  43. - `DATABASE_URL` — auto-wired Postgres connection string
  44. #### Optional but Recommended
  45. - `OPENROUTER_API_KEY` — model key so bots work out of the box (users can also connect models per-user in the UI)
  46. - `SANDBOX_PROVIDER` — `e2b`, `daytona`, `box`, or `none` (default: `e2b`)
  47. - `E2B_API_KEY` / `DAYTONA_API_KEY` / `BOX_API_KEY` — matching key for the chosen provider
  48. - `SIGNUP_ALLOWLIST` — comma-separated emails/domains allowed to sign up (configure before first API start to keep deployment private)
  49. - `SMTP_URL` — optional SMTP URL for password recovery
  50. - `EMAIL_FROM` — optional From header for outgoing email
  51. - `COMPOSIO_API_KEY` — optional Composio key for managed plugin catalog
  52. #### Do Not Edit (auto-wired)
  53. - `API_URL`, `WEB_ORIGIN`, `BETTER_AUTH_URL`, `RAKAZO_HOST` — wired to the web service domain
  54. - `API_PROXY_TARGET` — private API endpoint
  55. - `DATABASE_URL` — Postgres connection string
  56. - `DATA_DIR` — writable directory for bot workspace checkpoints
  57. ### 5. Deploy
  58. Click the **"Deploy"** button. Railway will:
  59. 1. Provision all four services
  60. 2. Run database migrations (`prisma migrate deploy`)
  61. 3. Health-check the API at `GET /health`
  62. 4. Assign a public domain to the web service
  63. ### 6. Post-Deploy Verification
  64. 1. **Register the first user immediately.** The first registered user becomes the deployment owner.
  65. 2. Access the web URL provided by Railway (e.g., `https://xxx.railway.app`).
  66. 3. Sign up with your email.
  67. 4. Verify the API health endpoint: `https://xxx.railway.app/health` should return OK.
  68. 5. (Optional) Test bot creation and a simple conversation.
  69. ### 7. Important Notes
  70. - **ENCRYPTION_KEY**: Never regenerate after the first start — stored credentials would become undecryptable.
  71. - **First user is owner**: Register immediately after deploy to claim ownership.
  72. - **Private deployment**: Set `SIGNUP_ALLOWLIST` before the first API start.
  73. - **Sandbox provider**: Without a key, the product boots and bots chat, but computer tools are unavailable.
  74. - **Railway trial**: Free tier provides $5.00 or 30 days. **Note: The free plan may not have enough resources to provision all 4 services (web, api, worker, postgres). If you see "Free plan resource provision limit exceeded", upgrade to a paid plan (Hobby $5/mo or Pro) before deploying.**
  75. - **Resource requirements**: The template deploys 4 services. The free tier's resource limits may be insufficient. Consider the Hobby plan ($5/month) or higher.
  76. ### 8. Alternative: External Postgres (3 services, no Postgres on Railway)
  77. If the free plan's 3-service limit is insufficient for all 4 services, use an external Postgres database:
  78. **Free external Postgres providers:**
  79. - [Neon](https://neon.tech) — free tier, 0.5 GB storage
  80. - [Supabase](https://supabase.com) — free tier, 500 MB
  81. **Steps:**
  82. 1. Create a database on the external provider
  83. 2. Get the connection string: `postgresql://user:pass@host:port/dbname?sslmode=require`
  84. 3. Deploy only `web`, `api`, `worker` on Railway (3 services)
  85. 4. Set `DATABASE_URL` in both `api` and `worker` to the external connection string
  86. 5. Ensure `ENCRYPTION_KEY` is shared between `api` and `worker`
  87. **Resource requirements (minimum):**
  88. | Service | Min RAM | Recommended |
  89. |---------|---------|-------------|
  90. | web (Vite) | 128 MB | 256 MB |
  91. | api (Hono) | 256 MB | 512 MB |
  92. | worker (Graphile) | 256 MB | 512 MB |
  93. ### 9. Alternative: Docker Compose Self-Hosting
  94. For full control over resources, deploy on your own server:
  95. ```bash
  96. git clone https://github.com/elie222/rakazo.git
  97. cd rakazo/infra/compose
  98. cp .env.example .env
  99. # Edit .env: set POSTGRES_PASSWORD, OPENROUTER_API_KEY, etc.
  100. docker compose -f docker-compose.prod.yml up -d --build
  101. ```
  102. Requirements: Linux server, Docker + Docker Compose, 4 GB RAM / 2 CPU minimum (8 GB recommended).
  103. ### 10. Alternative: GitHub Codespaces as External Postgres
  104. Use a GitHub Codespace to run Postgres as an external database for Railway:
  105. **Setup:**
  106. 1. Go to https://github.com/phycomp/codespaces
  107. 2. Click "Code" → "Codespaces" → "Create codespace on main"
  108. 3. Choose 4+ cores, 8GB+ RAM machine
  109. 4. Wait for the setup script to complete (installs Rakazo + Postgres)
  110. 5. In the Codespace terminal, get the Postgres connection string:
  111. ```bash
  112. # Postgres runs on port 5432 inside the Codespace
  113. # Use the Codespace's forwarded port URL
  114. echo "postgresql://postgres:password@localhost:5432/rakazo?sslmode=disable"
  115. ```
  116. 6. Make port 5432 public in the Codespace "Ports" tab
  117. 7. Use the forwarded URL as `DATABASE_URL` in Railway
  118. **Limitations:**
  119. - Codespaces sleep after 30 min of inactivity
  120. - Codespaces are deleted after 30 days of inactivity
  121. - Free tier: 60 hours/month for 2-core, 120 hours for 4-core
  122. - Not suitable for production; use for development/testing only
  123. **Recommended:** Use Neon (https://neon.tech) or Supabase (https://supabase.com) for a permanent free Postgres database instead.
  124. | Issue | Solution |
  125. |-------|----------|
  126. | Free plan resource limit exceeded | Railway free tier cannot provision 4 services; upgrade to Hobby ($5/mo) or Pro plan |
  127. | API container exits immediately | Check `POSTGRES_PASSWORD` is set and Postgres healthcheck passes |
  128. | Bots can't use computer tools | Set `SANDBOX_PROVIDER` and matching API key |
  129. | Can't sign up | Check `SIGNUPS_ENABLED` is true and `SIGNUP_ALLOWLIST` if set |
  130. | Stored credentials undecryptable | ENCRYPTION_KEY was regenerated — restore from backup |
  131. ## Quick Reference
  132. ```
  133. Template URL: https://railway.com/deploy/rakazo
  134. Deploy URL: https://railway.com/new/template/rakazo
  135. Station: https://station.railway.com/all-templates/49594aec-af0d-44fd-b143-ce05be3dd1e9
  136. Source: https://github.com/elie222/rakazo
  137. Image: ghcr.io/elie222/rakazo/app:v0.3.3
  138. ```
README.md · README · 31 lines
  1. # deploy-rakazo
  2. A skill for deploying [Rakazo](https://github.com/elie222/rakazo) — an open-source platform for persistent AI teammates with memory, routines, and their own computers — on [Railway](https://railway.com) using the official one-click template.
  3. ## What it covers
  4. - Railway template deployment (web, api, worker, postgres)
  5. - Environment variable configuration (OpenRouter, sandbox providers, auth secrets)
  6. - Post-deploy verification (first user registration, health check)
  7. - Common issues and troubleshooting
  8. ## Template
  9. - **Template URL:** https://railway.com/deploy/rakazo
  10. - **Deploy URL:** https://railway.com/new/template/rakazo
  11. - **Source:** https://github.com/elie222/rakazo
  12. - **Image:** ghcr.io/elie222/rakazo/app:v0.3.3
  13. ## Usage
  14. This skill is designed for AI agents. When a user asks to deploy Rakazo on Railway, the agent follows the steps in `SKILL.md`:
  15. 1. Open the Railway template
  16. 2. Sign in to Railway (GitHub/Google/email)
  17. 3. Review and configure environment variables
  18. 4. Deploy all four services
  19. 5. Verify post-deployment (register first user, check health)
  20. ## License
  21. This skill documents the deployment process for Rakazo. Rakazo itself is licensed under its own terms — see https://github.com/elie222/rakazo for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.