> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinykit.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Railway

> Deploy tinykit to Railway with one click

[Railway](https://railway.app) is the easiest way to deploy tinykit. One click, automatic HTTPS, and persistent storage included.

## One-Click Deploy

<Card title="Deploy to Railway" icon="train" href="https://railway.com/deploy/tinykit?referralCode=RCPU7k&utm_medium=integration&utm_source=template&utm_campaign=generic">
  Click to deploy tinykit to Railway in under 5 minutes.
</Card>

***

## What You'll Need

1. A [Railway account](https://railway.app) (free tier available)
2. An AI API key from one of:
   * [Anthropic](https://console.anthropic.com/) (Claude)
   * [OpenAI](https://platform.openai.com/api-keys) (GPT-4)
   * [Google AI Studio](https://aistudio.google.com/apikey) (Gemini)

***

## Step-by-Step Setup

<Steps>
  <Step title="Click Deploy Button">
    Click the "Deploy to Railway" button above, or go to the [tinykit Railway template](https://railway.com/deploy/tinykit?referralCode=RCPU7k\&utm_medium=integration\&utm_source=template\&utm_campaign=generic).
  </Step>

  <Step title="Configure Environment Variables">
    Railway will prompt you to set environment variables:

    | Variable                    | Required | Description                              |
    | --------------------------- | -------- | ---------------------------------------- |
    | `LLM_PROVIDER`              | Yes      | `anthropic`, `openai`, or `gemini`       |
    | `LLM_API_KEY`               | Yes      | Your API key                             |
    | `LLM_MODEL`                 | No       | Model name (defaults to provider's best) |
    | `POCKETBASE_ADMIN_EMAIL`    | Yes      | Admin email for database                 |
    | `POCKETBASE_ADMIN_PASSWORD` | Yes      | Admin password (min 8 chars)             |

    Example configuration:

    ```
    LLM_PROVIDER=anthropic
    LLM_API_KEY=sk-ant-api03-...
    LLM_MODEL=claude-sonnet-4-20250514
    POCKETBASE_ADMIN_EMAIL=admin@yourdomain.com
    POCKETBASE_ADMIN_PASSWORD=your-secure-password
    ```
  </Step>

  <Step title="Deploy">
    Click "Deploy" and wait 2-3 minutes for the build to complete.
  </Step>

  <Step title="Access Your Instance">
    Once deployed, Railway provides a URL like `your-app.railway.app`.

    * **Builder**: `your-app.railway.app/tinykit`
    * **Production apps**: `your-app.railway.app/`
  </Step>
</Steps>

***

## Adding Custom Domains

<Steps>
  <Step title="Open Railway Settings">
    Go to your Railway project → Settings → Domains
  </Step>

  <Step title="Add Domain">
    Click "Add Domain" and enter your domain (e.g., `app.yourdomain.com`)
  </Step>

  <Step title="Configure DNS">
    Add a CNAME record pointing to your Railway URL:

    ```
    app.yourdomain.com  CNAME  your-app.railway.app
    ```
  </Step>

  <Step title="Wait for SSL">
    Railway automatically provisions SSL certificates. This takes 1-5 minutes.
  </Step>
</Steps>

<Tip>
  You can add multiple domains to serve different apps. Each domain can point to a different tinykit project via [domain routing](/domain-routing).
</Tip>

***

## Persistent Storage

Railway automatically persists the `pocketbase/pb_data` directory. Your data survives:

* Redeploys
* Restarts
* Sleep/wake cycles

<Warning>
  Railway's free tier has storage limits. For production apps with significant data, consider upgrading to a paid plan.
</Warning>

***

## Costs

| Plan      | Monthly Cost | Includes                        |
| --------- | ------------ | ------------------------------- |
| **Hobby** | \~\$5        | 500 hours, 1GB storage          |
| **Pro**   | \$20 base    | Unlimited hours, more resources |

Plus your AI API costs (typically \$3-10/month for casual use).

***

## Updating Your Deployment

### Automatic Updates

Fork the tinykit repository and connect it to Railway for automatic deployments on push.

### Manual Updates

1. Go to your Railway project
2. Click "Redeploy" to pull the latest changes

***

## Environment Variables Reference

| Variable                    | Default   | Description                                           |
| --------------------------- | --------- | ----------------------------------------------------- |
| `LLM_PROVIDER`              | -         | AI provider: `anthropic`, `openai`, `gemini`          |
| `LLM_API_KEY`               | -         | Your AI API key                                       |
| `LLM_MODEL`                 | varies    | Model to use (e.g., `claude-sonnet-4-20250514`)       |
| `LLM_BASE_URL`              | -         | Custom API endpoint (for OpenAI-compatible providers) |
| `POCKETBASE_ADMIN_EMAIL`    | -         | Pocketbase admin email                                |
| `POCKETBASE_ADMIN_PASSWORD` | -         | Pocketbase admin password                             |
| `PORT`                      | `3000`    | Server port (Railway sets this automatically)         |
| `HOST`                      | `0.0.0.0` | Server host                                           |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Deploy fails with 'Pocketbase failed to start'">
    Check that your `POCKETBASE_ADMIN_EMAIL` and `POCKETBASE_ADMIN_PASSWORD` are set. The password must be at least 8 characters.
  </Accordion>

  <Accordion title="AI responses return errors">
    Verify your `LLM_API_KEY` is correct and has credits. Check the Railway logs for specific error messages.
  </Accordion>

  <Accordion title="Custom domain shows SSL error">
    Wait 5-10 minutes for SSL provisioning. If it persists, verify your DNS records are correct.
  </Accordion>

  <Accordion title="Data disappeared after redeploy">
    Railway should persist `/pocketbase/pb_data`. If data is lost, check that you haven't accidentally removed the volume in Railway settings.
  </Accordion>

  <Accordion title="App is slow to respond">
    Railway's free tier sleeps after inactivity. The first request after sleep takes 10-20 seconds. Upgrade to a paid plan for always-on performance.
  </Accordion>
</AccordionGroup>

***

## Logs and Monitoring

Access logs from the Railway dashboard:

1. Go to your project
2. Click on the service
3. View "Deployments" for build logs
4. View "Logs" for runtime logs

Look for:

* `Starting Pocketbase...` → Database startup
* `Pocketbase is ready!` → Database ready
* `Starting SvelteKit server...` → App startup