> ## 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.

# Security

> Security features and best practices

tinykit is designed for **self-hosted deployments** where you control the server. This gives you full control over security, but also means you're responsible for it.

## Security Model

<Info>
  Since tinykit is self-hosted (one server = one team), there's no multi-tenant isolation. All authenticated users can access all projects on that instance.
</Info>

### What's Protected

| Layer               | Protection                                          |
| ------------------- | --------------------------------------------------- |
| **Builder access**  | Pocketbase authentication required for `/tinykit`   |
| **API keys**        | Stored server-side in `.env`, never sent to browser |
| **File operations** | Scoped to workspace directory                       |
| **Preview**         | Sandboxed iframe with restricted permissions        |
| **Database**        | Pocketbase with collection-level access rules       |

***

## Built-in Protections

tinykit includes several security measures out of the box:

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock">
    Pocketbase auth with JWT tokens and automatic refresh
  </Card>

  <Card title="Path Traversal Protection" icon="shield">
    All file paths validated, `../` attacks blocked
  </Card>

  <Card title="Origin Checking" icon="globe">
    Cross-origin requests blocked for data APIs
  </Card>

  <Card title="Sandboxed Preview" icon="box">
    Preview runs in isolated iframe with `allow-scripts allow-same-origin`
  </Card>

  <Card title="Server-side Secrets" icon="key">
    API keys and credentials never exposed to client
  </Card>

  <Card title="Pocketbase Proxy" icon="server">
    Database accessed via same-origin proxy at `/_pb/`
  </Card>
</CardGroup>

***

## Production Checklist

Before exposing your tinykit instance to the public:

<Steps>
  <Step title="Protect the Builder">
    The `/tinykit` path gives full access to your codebase. Add authentication before going public.

    <Warning>
      **Critical:** Never expose `/tinykit` without authentication in production.
    </Warning>
  </Step>

  <Step title="Use Environment Variables">
    Never hardcode API keys or secrets. Use `.env` for configuration.

    ```env theme={null}
    LLM_API_KEY=sk-...
    ```
  </Step>

  <Step title="Enable HTTPS">
    Railway and most platforms provide HTTPS automatically. Never run without it.
  </Step>

  <Step title="Set Up Monitoring">
    Watch for unusual traffic patterns or error spikes.
  </Step>
</Steps>

***

## Scheduling PocketBase Backups

Your PocketBase database (`pb_data`) contains all your data. Regular backups are essential.

### Manual Backups

Access the PocketBase admin at `/_pb/_` and use the built-in backup feature under **Settings > Backups**.

### Automated Backups

<Tabs>
  <Tab title="Cron + Docker">
    Create a backup script and schedule it with cron:

    ```bash theme={null}
    # backup.sh
    #!/bin/bash
    BACKUP_DIR="/path/to/backups"
    CONTAINER="tinykit"
    DATE=$(date +%Y%m%d_%H%M%S)

    # Stop writes temporarily (optional, for consistency)
    docker exec $CONTAINER /app/pocketbase/pocketbase backup

    # Copy the backup
    docker cp $CONTAINER:/app/pocketbase/pb_data/backups/. $BACKUP_DIR/

    # Keep only last 7 days
    find $BACKUP_DIR -name "*.zip" -mtime +7 -delete
    ```

    Schedule with cron:

    ```bash theme={null}
    # Run daily at 2am
    0 2 * * * /path/to/backup.sh
    ```
  </Tab>

  <Tab title="Volume Snapshot">
    If using a named volume, back it up directly:

    ```bash theme={null}
    # Create backup
    docker run --rm \
      -v tinykit-data:/data \
      -v $(pwd):/backup \
      alpine tar czf /backup/pb_data_$(date +%Y%m%d).tar.gz -C /data .

    # Restore from backup
    docker run --rm \
      -v tinykit-data:/data \
      -v $(pwd):/backup \
      alpine sh -c "cd /data && tar xzf /backup/pb_data_20231215.tar.gz"
    ```
  </Tab>
</Tabs>

<Warning>
  Test your restore process before you need it. A backup you can't restore is worthless.
</Warning>

***

## Adding Authentication

To protect the `/tinykit` route, you have several options:

<Tabs>
  <Tab title="PocketBase Auth (Built-in)">
    tinykit uses PocketBase for authentication. Create users in the PocketBase admin (`/_pb/_`) and they can log in to access the builder.

    * Email/password authentication
    * JWT tokens with automatic refresh
    * Per-user accounts
  </Tab>

  <Tab title="Reverse Proxy">
    Add authentication at the proxy level (nginx, Cloudflare Access, etc.):

    ```nginx theme={null}
    location /tinykit {
      auth_basic "Admin Area";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://localhost:5173;
    }
    ```
  </Tab>

  <Tab title="IP Whitelist">
    Only allow access from specific IP addresses (good for internal tools).

    ```nginx theme={null}
    location /tinykit {
      allow 203.0.113.0/24;
      deny all;
      proxy_pass http://localhost:5173;
    }
    ```
  </Tab>
</Tabs>

***

## Reporting Vulnerabilities

Found a security issue? Please report it responsibly:

<Card title="Report a Vulnerability" icon="bug" href="https://github.com/tinykit-studio/tinykit/security/advisories/new">
  Open a private security advisory on GitHub
</Card>

We take security seriously and will respond promptly to legitimate reports.